# 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.

[Video: Claude Code builds a dock through Moor's MCP server.](https://moorapp.com/video/ai-agent.mp4)

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](/docs/automation/#command-line-moor)). 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**:

```sh
claude mcp add moor -- moor mcp
```

**Codex**: add this to `~/.codex/config.toml`:

```toml
[mcp_servers.moor]
command = "moor"
args = ["mcp"]
```

**Cursor**: add this to `~/.cursor/mcp.json` (or a project's `.cursor/mcp.json`):

```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](/docs/automation/#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](/docs/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](/docs/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](/docs/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](/docs/hold/): read or change its settings (**Read text in images** and the [screenshot stack](/docs/hold/#screenshots)), `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](/docs/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](/docs/widgets/#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](/docs/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](/docs/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.

```sh
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.

```sh
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](/docs/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"`) |

```sh
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`:

```sh
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:

```sh
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](/docs/parts/), 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](/docs/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](/docs/hold/#screenshots), 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](/docs/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](/docs/full-dock/)). `runningStyle` is `apps` (the default) or `windows`, which shows one button per open window, like a taskbar (see [Taskbar mode](/docs/docks/#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](/docs/docks/#the-shelf).

### Errors

Errors come back with an HTTP status and a message written for a person:

```json
{"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](/docs/privacy-and-safety/).
- **Want a safety net?** Before letting an agent rework your setup, save a backup with **Settings → Sync & Backup → Export All Profiles…**.

---
Source: https://moorapp.com/docs/api/
