MCP server and local API
Ask an AI agent to set up your docks and it does it, the same way you would by hand. Moor includes an MCP server for agents (Claude Code, Codex, Cursor and any other MCP client) and a local API for scripts. Both can read and change everything you can change in Moor: profiles, Custom Docks and their items, themes, widgets, settings and commands.
It's on your Mac only. Nothing listens on a network port, and nothing leaves your Mac.
What you can ask for
Once it's set up, just ask:
- “Put a dock on the left of my second display with Xcode, Terminal and the Agents widget.”
- “Make a Writing profile that hides Apple's Dock and shows only Pages, Safari and a clock.”
- “Switch to my Work profile.” Then: “Undo that.”
- “Add my Downloads folder to the Coding dock as a grid, newest first.”
- “Duplicate the Glass theme, give it rounder corners, and use it on every dock.”
- “Show the build status in my Custom widget: 3 failing, in red.”
The agent starts by reading your current setup (profiles, docks and themes), so it can use the names you already have.
Setting it up
The quick way: the setup guide has a Use Moor with your AI agent step, and Settings → Automation has the same buttons. Moor finds Claude Code, Codex and Cursor on your Mac and connects each with one click (no Terminal, nothing else to install). Restart the agent afterwards.
By hand: the MCP server is the moor command, so install it first: Settings → Sync & Backup → Install Command-Line Tool… (see Command line). Moor must be running, and Settings → Automation → Let apps and agents control Moor must be on (it's on unless you turned it off).
Claude Code:
claude mcp add moor -- moor mcp
Codex: add this to ~/.codex/config.toml:
[mcp_servers.moor]
command = "moor"
args = ["mcp"]
Cursor: add this to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):
{
"mcpServers": {
"moor": { "command": "moor", "args": ["mcp"] }
}
}
Any other MCP client: run moor mcp as a stdio server. If the client doesn't find moor on your PATH, use the full path the installer showed you, like /usr/local/bin/moor or ~/.local/bin/moor.
If Moor isn't running, or the setting is off, the agent is told so and can tell you.
Tools
| Tool | Does |
|---|---|
moor_get_state | The active profile, and every profile, dock and theme by id and name. Agents call this first |
moor_list_profiles | Every profile in full |
moor_switch_profile | Switch to a profile |
moor_create_profile | New profile: from the current Dock, empty, or a copy of another |
moor_update_profile | Rename, Dock mode, which docks it shows, Dock settings, color, symbol |
moor_list_docks · moor_get_dock | Every Custom Dock, or one, with its items |
moor_create_dock | New dock with items, placement, behavior and theme, optionally attached to a profile |
moor_update_dock | Rename, move to another edge or display, auto-hide and other behavior, theme |
moor_add_item · moor_update_item · moor_remove_item · moor_move_item | Change a dock's items |
moor_list_themes · moor_create_theme · moor_update_theme | Dock themes (built-in themes are duplicated, not edited) |
moor_widget_catalog | Every widget, with its sizes and default settings |
moor_set_custom_widget | Update the Custom widget |
moor_get_settings · moor_update_settings | Moor's settings |
moor_run_command | Next or previous profile, back to the last one, undo, picker, search, edit mode, or any moor:// link |
moor_helm | Helm: list layouts, snap the front window to a target, save, restore or delete a layout, change a layout's restore options (layout_options), and read or change the Window Switcher and snapping settings (settings, update_settings) |
moor_mast | Mast: read or change its settings, Menu Bar Appearance included (settings, update_settings), show or hide the hidden menu bar items, and list, add, configure or remove menu bar widgets |
moor_deck | Deck: list, add, move, resize, configure or remove desktop widgets, and change dimming, edit mode and whether the active profile has its own widgets |
moor_hold | Hold: read or change its settings (Read text in images and the screenshot stack), open Hold on a shelf or with a search, and show_screenshots or clear_screenshots. It never moves, trashes or lists your files |
moor_parts | List Moor's parts and which are on, or turn one on or off (action: list, enable, disable; part: docks, helm, mast, bar, deck, hold) |
moor_memory | Memory: memory in use, the last cleans and the settings (status), start a clean (clean, mode clean or super), and read or change the cleaning settings (settings, update_settings). Clean shows macOS's password prompt on screen for you to answer. It never quits apps |
moor_bar | Design the person's menu bar: read Moor Bar's layout and look, add, move, change and remove sections (zone, index, display), change the layout per display and the look (action: get, layout, add_section, move_section, update_section, remove_section, update_layout, style, update_style) |
Wherever a tool asks for a profile, dock or theme, an agent can give its name instead of its id.
Parts
Moor's parts (Docks, Helm, Mast, Moor Bar, Deck and Hold) can be listed and turned on or off through the API, the moor_parts tool and the moor parts command. {id} is docks, helm, mast, bar, deck or hold (not case-sensitive; the name works too). Turning a part on may make macOS ask you for a permission, so an agent can start one but you still allow it.
moor parts # on or off, name, what it replaces
moor parts --json
moor parts enable helm
moor parts disable helm
moor api GET /v1/parts/helm
moor api POST /v1/parts/mast/enable
Docks are always on, so disabling them gives a 409. A part that doesn't exist gives a 404.
Each part's own settings and actions are in the API too. Reading works whether the part is on or off, except Deck, which answers only while it's on. Changing a setting or doing something needs the part on, or the reply is a 409 that says to turn it on. Shortcuts are listed but can only be set in Moor's settings.
moor api PATCH /v1/helm/settings '{"snapping": {"gap": 12}, "switcher": {"largePreviews": true}}'
moor api PATCH /v1/mast/settings '{"autoHideDelay": 30, "appearance": {"mode": "theme", "theme": "Midnight"}}'
moor api POST /v1/mast/widgets '{"kind": "time.clock", "config": {"use24h": true}}'
moor api POST /v1/deck/widgets '{"kind": "calendar.nextEvent", "size": "wide", "x": 40, "y": 40}'
moor api PATCH /v1/deck/settings '{"dimming": "never"}'
moor api POST /v1/hold/open '{"search": "pdfs from last week"}'
Colours in Menu Bar Appearance are #RRGGBB. The border colour can be #RRGGBBAA, where the last two digits are its opacity. A theme or a display can be given by name or id. Turning on menu bar search, or picking split islands, may make macOS ask you for Accessibility.
Moor Bar
Moor Bar's layout is three zones per bar, leading, center and trailing, each a list of sections in left-to-right order. There's one shared bar, or one per display while sameOnEveryDisplay is off. A section is {"id", "type", …its options}:
type | Options |
|---|---|
moorMenu, appName, divider | none |
clock | format: a preset (time, timeSeconds, dayTime, dateTime, date, time24) or a date pattern of up to 64 characters, like EEE d MMM HH:mm |
widget | kind (from GET /v1/widgets/catalog) and config (merged into its defaults). It gets the size that fits the bar. Shown with its widget |
text | text: one line, up to 60 characters |
spacer | width: 2 to 200 points |
appleMenu, appMenus, statusItems, controlCenter | none. They need Accessibility ("needsAccessibility": true); without it the bar shows one "Allow Accessibility" button in their place. GET /v1/bar says whether it's allowed ("accessibility") |
moor api POST /v1/bar/sections '{"type": "text", "text": "Deep work", "zone": "center"}'
moor api PATCH /v1/bar/sections/<id> '{"zone": "leading", "index": 0}'
moor api PATCH /v1/bar/layout '{"sameOnEveryDisplay": false, "displays": {"Studio Display": {"center": [{"type": "widget", "kind": "system.battery"}]}}}'
moor api PATCH /v1/bar/style '{"shape": "island", "theme": "Midnight", "fontSize": 14}'
In PATCH /v1/bar/layout, a zones object replaces the zones it names. Keep a section by listing {"id": …} (with any options to change); add one with {"type": …}. A display is given by name or id; null forgets its own bar. Every reply is the new state. Reading works with Moor Bar off; changes need it on (409 otherwise). A bad request changes nothing and says what's wrong (400).
HTTP API
Scripts can use the same API directly. It's HTTP with JSON, over a Unix socket at ~/Library/Application Support/Moor/moor.sock (or in MOOR_STORE_ROOT if you set it).
With curl:
SOCK="$HOME/Library/Application Support/Moor/moor.sock"
curl --unix-socket "$SOCK" http://localhost/v1/state
curl --unix-socket "$SOCK" -X POST http://localhost/v1/docks \
-H "Content-Type: application/json" \
-d '{"name": "Coding", "placement": {"edge": "left"}, "items": [{"type": "app", "bundleID": "com.apple.dt.Xcode"}, {"type": "app", "bundleID": "com.apple.Terminal"}]}'
curl --unix-socket "$SOCK" -X POST http://localhost/v1/profiles/Work/activate
Or with the moor command, which finds the socket for you and prints the reply as formatted JSON:
moor api GET /v1/state
moor api POST /v1/docks '{"name": "Coding"}'
moor api PATCH /v1/docks/Coding @dock.json # body from a file
echo '{"index": 0}' | moor api POST /v1/docks/Coding/items/<item id>/move -
moor api exits with status 1 when Moor answers with an error (the message goes to stderr), 2 for bad arguments, and 3 when Moor isn't running or the API is off.
Endpoints
| Method | Path | Does |
|---|---|---|
| GET | /v1 | Moor's version and the API version |
| GET | /v1/state | Active profile; profiles, docks and themes by id and name |
| GET | /v1/profiles · /v1/profiles/{id} | Every profile, or one |
| POST | /v1/profiles | Create: {name, from?, mode?}. from is current (the Dock as it is now), empty, or a profile to copy |
| PATCH | /v1/profiles/{id} | Change name, mode, customDockIDs, settings, color, symbol, display rules. A profile's Context Profiles rules come back in GET but can't be changed here; edit them in Moor |
| DELETE | /v1/profiles/{id} | Delete (not the last one) |
| POST | /v1/profiles/{id}/activate | Switch to it |
| GET | /v1/docks · /v1/docks/{id} | Every Custom Dock, or one |
| POST | /v1/docks | Create: {name, items?, placement?, behavior?, themeID?, profile?} |
| PATCH | /v1/docks/{id} | Change name, placement, behavior, themeID, runningLayout, runningStyle |
| DELETE | /v1/docks/{id} | Delete (and remove it from profiles) |
| POST | /v1/docks/{id}/items | Add {item, index?} (at the end without an index) |
| PATCH | /v1/docks/{id}/items/{itemID} | Change an item's label, a widget's size or settings, a folder's view, sort or display |
| DELETE | /v1/docks/{id}/items/{itemID} | Remove an item |
| POST | /v1/docks/{id}/items/{itemID}/move | Move it: {index} |
| GET | /v1/themes · /v1/themes/{id} | Every theme, or one |
| POST | /v1/themes | Create: {name, from?, …} |
| PATCH | /v1/themes/{id} | Change one of your themes (light, dark and layout are merged) |
| DELETE | /v1/themes/{id} | Delete one of your themes (docks using it go back to Glass) |
| GET | /v1/widgets/catalog | Every widget: kind, name, sizes, default size and settings, whether it needs an account |
| POST | /v1/widgets/custom/{key} | Update the Custom widget (value, title, badge, color, symbol) |
| GET | /v1/parts · /v1/parts/{id} | Every part, or one: id, name, replaces, summary, enabled, toggleable, permissions |
| POST | /v1/parts/{id}/enable · /v1/parts/{id}/disable | Turn a part on or off. Replies with the part. Docks can't be turned off (409) |
| POST | /v1/helm/snap/{target} | Move the front window: left, right, top, bottom, top-left, top-right, bottom-left, bottom-right, maximize, center, left-third, center-third, right-third, left-two-thirds, right-two-thirds, next-display, previous-display, restore. Needs Helm on (409 if off) |
| GET · POST | /v1/helm/layouts | Saved Helm layouts, or save one: {"name": "Coding", "display": "…"} (main display if left out) |
| GET · DELETE | /v1/helm/layouts/{id} | One layout, or delete it |
| PATCH | /v1/helm/layouts/{id} | A layout's restore options: openMissingApps (true or false), otherWindows (leave, minimize or hide). Needs Helm on |
| POST | /v1/helm/layouts/{id}/restore | Put a layout's windows back. Replies once it has started |
| GET · PATCH | /v1/helm/settings | switcher: enabled, switchOnRelease, allSpaces, largePreviews, showOn (focusedWindow, pointer, main). snapping: enabled, onlyWithModifier, gap (0 to 24 points). shortcuts is read-only. PATCH needs Helm on |
| GET · PATCH | /v1/mast/settings | revealOnScroll, revealOnClick, revealOnHover, revealWithMoorIcon, autoHide, autoHideDelay (5, 10, 15, 30 or 60), alwaysHidden, search, and appearance: mode (off, theme, custom), theme, fill (solid, gradient, glass), lightColor, lightSecondColor, darkColor, darkSecondColor, opacity (0 to 1), border, borderColor, borderWidth (0.5 to 4), shadow, shape (fullBar, roundedBar, splitIslands), allDisplays, displays. PATCH needs Mast on |
| POST | /v1/mast/show · /v1/mast/hide | Show the hidden menu bar items ({"all": true} for the always-hidden ones too), or hide them. Needs Mast on |
| GET · POST | /v1/mast/widgets | Menu bar widgets, left to right, or add one: {kind, config?}. It gets the size that fits the bar. Adding needs Mast on |
| PATCH · DELETE | /v1/mast/widgets/{id} | Change a menu bar widget's settings ({"config": {…}}, merged), or remove it. {id} can be the widget's kind when there's one of it. Needs Mast on |
| GET · PATCH | /v1/deck/settings | dimming (automatic, always, never), editing (edit mode), ownLayout (the active profile has its own widgets). profile and displays are read-only. Needs Deck on |
| GET · POST | /v1/deck/widgets | The active profile's desktop widgets with their display and place, or add one: {kind, size?, config?, display?, x?, y?}. x and y are points from the top left of the display, both or neither. Needs Deck on |
| PATCH · DELETE | /v1/deck/widgets/{id} | Change a desktop widget's size, config (merged), display, x and y, or remove it. Widgets snap to the grid and never overlap. Needs Deck on |
| GET · PATCH | /v1/hold/settings | readTextInImages, screenshots, keepAppleThumbnail, screenshotsCorner (bottomRight, bottomLeft, topRight, topLeft), screenshotsTimeout (seconds, 0 = until dismissed, up to 3600), screenRecordings, screenshotsFollow; shortcut and screenshotsShortcut are read-only. PATCH needs Hold on |
| POST | /v1/hold/screenshots/show · /clear | Fan out the screenshot stack, or take its unpinned captures off it (the files stay). Needs Hold on |
| POST | /v1/hold/open | Open Hold: {}, {"shelf": "downloads"} or {"search": "pdfs from last week"}. Shelves: images, screenshots, videos, music, documents, archives, apps, projects, downloads, duplicates, cleanUp. Needs Hold on |
| GET | /v1/bar | Moor Bar: enabled, displays (id, name, notch), layout, style and sectionTypes |
| GET · PATCH | /v1/bar/layout | The layout the active profile shows: sameOnEveryDisplay, shared and displays (zones of sections), and ownLayout (the active profile has its own bar; send true to give it one, a copy of the shared bar, or false to go back). profile is read-only. PATCH needs Moor Bar on |
| POST | /v1/bar/sections | Add a section: {type, …options, zone, index?, display?}. display only while each display has its own bar. Replies 201 with the section and the layout. Needs Moor Bar on |
| PATCH · DELETE | /v1/bar/sections/{id} | Move a section (zone, index) and change its options, or remove it. Needs Moor Bar on |
| GET · PATCH | /v1/bar/style | The look: mode (theme, custom), theme, fill, lightColor, lightSecondColor, darkColor, darkSecondColor, opacity, border, borderColor, borderWidth, shadow, shape (fullWidth, island), islandInset (0 to 40), heightOffset (-10 to 0), fontSize (11 to 16), itemSpacing (0 to 24). PATCH needs Moor Bar on |
| GET | /v1/memory | Memory now (used, physical, free, cachedFiles, compressed, appMemory, wired, swapUsed, pressure), the clean running (cleaning, or null), the last 20 cleans (log: id, mode, trigger, outcome, summary, freed, before, after, note…) and settings |
| POST | /v1/memory/clean | Start a clean: {"mode": "clean"} (the default; macOS shows the administrator password prompt on screen) or {"mode": "super"} (no password). Replies at once with its id; the result appears in GET /v1/memory's log. 409 while one is running, or for super while memory pressure is already high. A cancelled password prompt leaves no log entry. Never quits apps |
| GET · PATCH | /v1/memory/settings | automatic, onPressure (off, high, critical), whenFreeBelow, freeBelowGB (0.25 to 16), onSchedule, everyHours (1 to 24), automaticMode (clean, super), cooldownMinutes (15 to 1440), skipOnBattery, skipInFullScreen, skipDuringCalls, skipWhenIdle, notifyAfterAutomatic, idleMinutes (5 to 240), bigAppMB (100 to 16000), excludedApps (bundle ids). askForPassword is read-only here (403): only you turn it on, in Settings → Memory |
| GET · PATCH | /v1/settings | Moor's settings, including windowPreviews and previewDelay (0 to 1 second) for the docks. focusDockShortcut is read-only |
| POST | /v1/commands | {command}: next, prev, toggle, undo, picker, search, edit-docks, focus-off, snapshot. Or {url} with any moor:// link |
Three dock settings are worth knowing. runningLayout is scroll (the default) or wrap2, which wraps the running apps into two rows (see When the dock is full). runningStyle is apps (the default) or windows, which shows one button per open window, like a taskbar (see Taskbar mode). For placement, the Fill alignment is "fill": "fullLength"; any other alignment is "fill": "fitContent" with alignment set to start, center or end.
{id} is an id or a name (not case-sensitive). Replies are the same JSON Moor saves, so you can GET something, change it, and send it back. PATCH changes only the keys you send.
Items
Add items in this short form:
| Item | JSON |
|---|---|
| App | {"type": "app", "bundleID": "com.apple.Safari"} or {"type": "app", "path": "/Applications/Safari.app"} |
| Folder | {"type": "folder", "path": "~/Downloads", "view": "grid", "sort": "dateAdded", "display": "stack"}. view: auto, grid, fan, list; sort: dateAdded, name, kind, dateModified, dateCreated; display: stack, folder |
| File | {"type": "file", "path": "~/Documents/plan.pdf"} |
| Link | {"type": "url", "url": "https://moorapp.com", "label": "Moor"} |
| Widget | {"type": "widget", "kind": "time.clock", "size": "wide", "config": {}}. Kinds, sizes and settings are in /v1/widgets/catalog; leave out config for the defaults |
| Shortcut | {"type": "shortcut", "name": "Start Focus"} |
| Divider, spacer, Trash | {"type": "divider"}, {"type": "spacer", "small": false}, {"type": "trash"} |
| Open apps | {"type": "runningApps"}: apps that are open but not in the dock |
| Group | {"type": "group", "label": "Design", "items": [ … ]} |
Apps must be installed. Labels default to what Moor would show. The API can't add a Shelf.
Errors
Errors come back with an HTTP status and a message written for a person:
{"error": {"code": "not_found", "message": "There's no dock named “Lefty”."}}
| Status | code | When |
|---|---|---|
| 400 | bad_request | Something in the request is wrong (the message says what) |
| 404 | not_found | No profile, dock, theme, part or item with that id or name |
| 409 | conflict | Two things have that name (use the id), or the change isn't allowed, like deleting the last profile or turning off Docks |
| 503 | disabled | The API is turned off |
| 500 | internal | Something went wrong in Moor |
Privacy and safety
- On your Mac only. The API is a Unix socket only your user account can open. Nothing listens on a network port, so other computers and web pages can't reach it.
- API keys stay private. Keys and accounts for widgets are in your Keychain, and the API can't read or change them. An agent can add a revenue widget, but you connect the account yourself.
- Turn it off with Settings → Automation → Let apps and agents control Moor. Moor then stops listening.
- Same as doing it yourself. Every change goes through the same steps as Moor's own windows and menus, and syncs through iCloud if that's on. A profile switch can be undone (Undo in the menu, or ask the agent to undo it). Your original Dock is always kept, as described in Privacy & safety.
- Want a safety net? Before letting an agent rework your setup, save a backup with Settings → Sync & Backup → Export All Profiles….
This page as Markdown: /docs/api.md