Agents & 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 MCP server is the moor command, so install it first: Settings → Advanced → 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

Wherever a tool asks for a profile, dock or theme, an agent can give its name instead of its id.

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

{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:

Apps must be installed. Labels default to what Moor would show.

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”."}}

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 → Advanced → Export All Profiles….

This page as Markdown: /docs/api.md