Allume MCP Setup

Open Allume and go to Preferences → MCP (⌘, then click the MCP tab). Flip Enable MCP on.

Until MCP is enabled, AI clients cannot even see the tool catalog — tools/list is gated too, so connected clients will show no Allume tools at all until the toggle is on.

Under the Enable MCP toggle, pick an access mode:

• Read-only (default) — agents can search and read your boards; any write tools return an error
• Read-write — agents can also create cards, notes, boards, and chains; move and gather cards; update notes; and delete or undelete content

You can flip between modes at any time. There are no per-board sharing controls today — when MCP is enabled, agents can see every workspace and every board in your local Allume.

In the same Preferences → MCP tab, find the MCP Helper Path section and click Copy Path. This gives you the full path to the allume-cli helper binary bundled inside the Allume app — the exact path depends on where Allume is installed (Mac App Store, Setapp, etc.).

You’ll paste this path into your AI client’s config in the Integrations section below. Every supported client uses the same shape:

• Command: the path you just copied
• Args: ["mcp"]

If you’d rather configure clients with allume than a full bundled path, go to Preferences → CLI (a sibling of the MCP tab) and click Install. macOS will pop the standard admin auth panel — this is expected.

This creates a symlink at /usr/local/bin/allume. After installing, you can use /usr/local/bin/allume (or just allume) as the command anywhere this page shows the long bundled path. The shorter path survives Allume app moves and updates.

To uninstall, Allume shows you a rm /usr/local/bin/allume command to paste into Terminal. (Apple does not provide a sandboxed way for the app to remove the symlink it created — this manual step is the workaround.)

The MCP server lives inside the Allume Mac app — the allume-cli helper your AI client talks to is just a proxy that forwards each request over a sandboxed pipe to the app. If Allume is fully quit, there is nothing on the other end of that pipe, and your AI client will see a connection error.

You do not need to keep Allume in focus. Foreground or background is fine — as long as it’s in the Dock or running in the background, MCP is available.

Open Claude Desktop’s config file at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add an allume entry under mcpServers:

{
  "mcpServers": {
    "allume": {
      "command": "/Applications/Allume.app/Contents/MacOS/allume-cli",
      "args": ["mcp"]
    }
  }
}

Replace the command value with the path you copied from Allume (or use /usr/local/bin/allume if you installed the Terminal symlink). Restart Claude Desktop and the Allume tools will appear in any chat.

One command, using the path from Preferences → MCP → Copy Path:

claude mcp add allume -- /Applications/Allume.app/Contents/MacOS/allume-cli mcp

The -- separator is required so the trailing mcp is not parsed as a Claude flag.

Or edit the Claude Code global config file directly (typically ~/.claude.json) with the same command and args: ["mcp"] shape as the Claude Desktop example above.

Cursor uses the same mcpServers shape as Claude Desktop, in either of:

• ~/.cursor/mcp.json — global, available in every project
• <your-project>/.cursor/mcp.json — project-local

{
  "mcpServers": {
    "allume": {
      "command": "/Applications/Allume.app/Contents/MacOS/allume-cli",
      "args": ["mcp"]
    }
  }
}

In LM Studio, open the right-hand Program tab, click Install → Edit mcp.json, and add Allume under mcpServers:

{
  "mcpServers": {
    "allume": {
      "command": "/Applications/Allume.app/Contents/MacOS/allume-cli",
      "args": ["mcp"]
    }
  }
}

Save and LM Studio will load the server automatically. The file lives at ~/.lmstudio/mcp.json if you’d rather edit it directly.

ChatGPT (web and desktop) only connects to remote HTTPS MCP servers, and Allume MCP is local stdio only — your AI client spawns allume-cli mcp and talks to it over stdin/stdout. Allume does not expose an HTTPS endpoint, so ChatGPT cannot connect directly today.

If OpenAI adds local stdio support, or you bring your own bridge, that may change.

To debug a connection or browse the live tool catalog by hand, run the MCP Inspector directly against the helper:

npx @modelcontextprotocol/inspector "/Applications/Allume.app/Contents/MacOS/allume-cli" mcp

The Inspector shows the live tools/list, lets you call each tool by hand, and prints raw JSON-RPC traffic.

In read-only mode, agents can:

• list_workspaces — enumerate your workspaces
• search — substring search across boards, returning line-level snippets
• open — jump Allume’s UI to a specific document
• board_content — list cards on a board, with token filtering across title, body, URL, and filename
• card_content — read a single card; raw mode streams body or blob payloads
• card_pdf_page — extract one page from a PDF card

In read-write mode, agents can additionally:

• Create: note_create, url_create, card_create, board_create, chain_create
• Modify: card_move, card_gather, note_update, chain_update
• Reversible destructive: delete, undelete

Ink strokes are not individually exposed as a tool surface today — cards containing ink are visible as cards.

MCP is disabled until you manually enable it. Until you flip Enable MCP on in Preferences → MCP, every request from an AI client returns a friendly “MCP disabled” error — tools/list included, so clients can’t even see the catalog.

Beyond that user-consent gate, there are no tokens or OAuth to manage. The rest of the trust boundary is the macOS sandbox:

• The allume-cli helper lives inside the signed Allume app bundle, so only you (or something running as you) can spawn it
• The pipe it uses to talk to the Allume app lives in the App Group sandbox container — other apps can’t reach it

It depends on the client. When an agent reads a board through MCP, the contents of that board are handed to whichever model is answering the conversation:

• Cloud clients (Claude Desktop, Claude Code, Cursor) — the board contents are sent to that company’s servers (Anthropic, OpenAI, etc.) as part of the conversation. That’s how the agent uses them to answer.
• Local clients (LM Studio, or any local-model setup) — the model runs on your Mac, so the board contents stay on your Mac end-to-end. Nothing leaves your machine.

Either way, the helper binary itself only talks to the running Allume app on your Mac — it never sends data anywhere on its own.

Common causes, in order:

• “Allume not running” or connection failure — the Mac app needs to be open. The helper is just a proxy.
• AI client doesn’t list Allume after editing its config — most clients (Claude Desktop, Cursor, etc.) only pick up new MCP servers on launch. Fully quit and reopen the client.
• “MCP disabled” responses — flip Enable MCP on in Preferences.
• Write tools return an error — your workspace is in Read-only mode; switch to Read-write in Preferences.
• AI client sees no tools at all — same as above, MCP is not enabled.
• allume not found in Terminal — the symlink is not installed; use Preferences → CLI → Install, or point your client at the full helper path.
• Stopped working after an Allume update or move — the hard-coded path in your client config is stale. Open Preferences, copy the new path, and update the config.

Still stuck? Email adam@allume.com.