On this page

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.

Claude Code builds a dock through Moor's MCP server.

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:

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

ToolDoes
moor_get_stateThe active profile, and every profile, dock and theme by id and name. Agents call this first
moor_list_profilesEvery profile in full
moor_switch_profileSwitch to a profile
moor_create_profileNew profile: from the current Dock, empty, or a copy of another
moor_update_profileRename, Dock mode, which docks it shows, Dock settings, color, symbol
moor_list_docks · moor_get_dockEvery Custom Dock, or one, with its items
moor_create_dockNew dock with items, placement, behavior and theme, optionally attached to a profile
moor_update_dockRename, move to another edge or display, auto-hide and other behavior, theme
moor_add_item · moor_update_item · moor_remove_item · moor_move_itemChange a dock's items
moor_list_themes · moor_create_theme · moor_update_themeDock themes (built-in themes are duplicated, not edited)
moor_widget_catalogEvery widget, with its sizes and default settings
moor_set_custom_widgetUpdate the Custom widget
moor_get_settings · moor_update_settingsMoor's settings
moor_run_commandNext or previous profile, back to the last one, undo, picker, search, edit mode, or any moor:// link
moor_helmHelm: 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_mastMast: 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_deckDeck: list, add, move, resize, configure or remove desktop widgets, and change dimming, edit mode and whether the active profile has its own widgets
moor_holdHold: 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_partsList 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_memoryMemory: 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_barDesign 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}:

typeOptions
moorMenu, appName, dividernone
clockformat: a preset (time, timeSeconds, dayTime, dateTime, date, time24) or a date pattern of up to 64 characters, like EEE d MMM HH:mm
widgetkind (from GET /v1/widgets/catalog) and config (merged into its defaults). It gets the size that fits the bar. Shown with its widget
texttext: one line, up to 60 characters
spacerwidth: 2 to 200 points
appleMenu, appMenus, statusItems, controlCenternone. 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

MethodPathDoes
GET/v1Moor's version and the API version
GET/v1/stateActive profile; profiles, docks and themes by id and name
GET/v1/profiles · /v1/profiles/{id}Every profile, or one
POST/v1/profilesCreate: {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}/activateSwitch to it
GET/v1/docks · /v1/docks/{id}Every Custom Dock, or one
POST/v1/docksCreate: {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}/itemsAdd {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}/moveMove it: {index}
GET/v1/themes · /v1/themes/{id}Every theme, or one
POST/v1/themesCreate: {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/catalogEvery 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}/disableTurn 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/layoutsSaved 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}/restorePut a layout's windows back. Replies once it has started
GET · PATCH/v1/helm/settingsswitcher: 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/settingsrevealOnScroll, 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/hideShow the hidden menu bar items ({"all": true} for the always-hidden ones too), or hide them. Needs Mast on
GET · POST/v1/mast/widgetsMenu 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/settingsdimming (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/widgetsThe 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/settingsreadTextInImages, 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 · /clearFan out the screenshot stack, or take its unpinned captures off it (the files stay). Needs Hold on
POST/v1/hold/openOpen 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/barMoor Bar: enabled, displays (id, name, notch), layout, style and sectionTypes
GET · PATCH/v1/bar/layoutThe 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/sectionsAdd 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/styleThe 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/memoryMemory 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/cleanStart 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/settingsautomatic, 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/settingsMoor'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:

ItemJSON
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”."}}
StatuscodeWhen
400bad_requestSomething in the request is wrong (the message says what)
404not_foundNo profile, dock, theme, part or item with that id or name
409conflictTwo things have that name (use the id), or the change isn't allowed, like deleting the last profile or turning off Docks
503disabledThe API is turned off
500internalSomething went wrong in Moor

Privacy and safety

This page as Markdown: /docs/api.md