MCP Server

Cairn ships a bundled stdio MCP server. Connect Claude Desktop, OpenCode, Cursor, or any MCP-compatible client and give it direct read/write access to your workspace. Changes appear in the Cairn UI instantly.

What is MCP?

Model Context Protocol (MCP) is an open standard published by Anthropic for exposing structured tools to AI clients. An MCP server runs as a local process alongside your AI client; the client calls tools from the server to read and write data. Cairn's MCP server exposes your entire workspace — notes, tasks, projects — to any compatible client.

Where the server binary lives

The MCP server is a self-contained binary bundled inside the installed Cairn app. No Node.js required, no separate install.

macOS

/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp

Windows

C:\Users\<user>\AppData\Local\Programs\Cairn\resources\app.asar.unpacked\dist-mcp\cairn-mcp.exe

Linux

/opt/Cairn/resources/app.asar.unpacked/dist-mcp/cairn-mcp

AppImage installs may use a different path. If unsure, run find / -name cairn-mcp 2>/dev/null to locate the binary.

Running from source

/path/to/cairn/dist-mcp/cairn-mcp

Configuring Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your platform:

{
  "mcpServers": {
    "cairn": {
      "command": "/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"
    }
  }
}

On Windows, use the Windows binary path and ensure the .exe extension is included. Forward slashes work in JSON on Windows. Restart Claude Desktop after saving.

Configuring Cursor

Cursor uses the same mcpServers format as Claude Desktop. Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cairn": {
      "command": "/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"
    }
  }
}

Configuring Cline

Cline (VS Code extension) uses the same format. Add via the Cline settings UI or directly in your VS Code settings.json:

{
  "mcpServers": {
    "cairn": {
      "command": "/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"
    }
  }
}

Configuring OpenCode

In your project repo, create .opencode/config.json:

{
  "mcp": {
    "cairn": {
      "type": "local",
      "command": ["/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"],
      "enabled": true
    }
  }
}

How writes appear instantly

The Cairn app polls the SQLite database using WAL (Write-Ahead Logging) change detection. When the MCP server writes a note or task, the change is committed to the database and the app detects it within milliseconds — no restart required, no manual refresh. The UI updates in place.

MCP notifications

When an MCP tool writes to your workspace, Cairn fires a native OS notification within one second — visible even when the app is minimised. The menu bar tray icon shows a badge count for unread MCP updates. Clicking it brings Cairn to front and clears the badge.

All write operations trigger a notification — this includes notes, tasks, projects, dashboards, and Idea Flow tools.

Tool reference

All 46 tools exposed by the Cairn MCP server, grouped by category.

Context

Tool	Read / Write	Description
`get_cairn_context`	Read	Full orientation: workspaces, projects, column IDs, tool list, conventions. Call once at session start.
`get_project_context_pack`	Read	Single-call bundle: project metadata + pinned notes + open tasks + recent activity
`resolve_project`	Read	Find a project by name (fuzzy, case-insensitive) and return its ID and column IDs
`get_project_summary`	Read	Column breakdown, card counts, pinned notes, recent activity
`list_recent_activity`	Read	Recently created or updated notes and tasks, sorted newest first

Notes

Tool	Read / Write	Description
`get_note`	Read	Full markdown content, linked IDs, and metadata of a note by ID
`list_notes`	Read	List all notes in a project
`search_notes`	Read	Full-text search across notes
`create_note`	Write	Create a markdown note
`import_note_from_file`	Write	Import a local file as a note — server reads from disk, no need to inline content
`ensure_note`	Write	Idempotent create-or-update by title — prevents duplicate notes on re-run
`append_to_note`	Write	Append content to a note without re-sending the full body
`patch_note`	Write	Surgically replace a string inside a note — no need to re-send the full content
`update_note`	Write	Update a note's title, content, or pinned state
`move_note`	Write	Move a note to a different project
`delete_note`	Delete	Permanently delete a note. Cannot be undone.

Tasks

Tool	Read / Write	Description
`get_task`	Read	Full task detail by ID — includes `blockedByIds`
`list_tasks`	Read	All tasks in a project grouped by column
`list_ready_tasks`	Read	Only unblocked, active tasks — use this instead of `list_tasks` to find work that can start now
`search_tasks`	Read	Full-text search across task cards
`create_task`	Write	Create a task card in a column
`update_task`	Write	Update a task's title, description, priority, due date, column, or assignee
`update_task_status`	Write	Move a single task to a different column
`bulk_update_task_status`	Write	Move multiple tasks to the same column in one call
`link_note_to_task`	Write	Bidirectionally link a note and a task card
`block_task`	Write	Mark a task as blocked by another task in the same project. Circular dependencies are rejected.
`unblock_task`	Write	Remove a blocking dependency between two tasks
`delete_task`	Delete	Permanently delete a task card. Cannot be undone.

Projects

Tool	Read / Write	Description
`create_project`	Write	Create a project with default board columns (Backlog, Todo, In Progress, Review, Done)
`update_project`	Write	Update a project's name, description, icon, status, or priority
`delete_project`	Delete	Permanently delete a project and all its contents. Cannot be undone.

Dashboards

Tool	Read / Write	Description
`get_dashboard_constants`	Read	Returns the `window.cairn` API reference for writing dashboard HTML. Call before `create_dashboard`.
`create_dashboard`	Write	Create a live HTML dashboard in a project. HTML must be self-contained with inline CSS/JS.
`update_dashboard`	Write	Update an existing dashboard's title or HTML

Idea Flow

Tool	Read / Write	Description
`get_idea_flow`	Read	Full canvas graph — all nodes and edges — with note and task content resolved inline
`get_idea_flow_rules`	Read	Node type data shapes, group conventions, and positioning rules. Call before creating nodes.
`create_idea_flow_node`	Write	Add a node to the canvas (idea, note_ref, task_ref, group, url, ai_summary)
`update_idea_flow_node`	Write	Update a node's data fields or canvas position; data is merged, not replaced
`create_idea_flow_edge`	Write	Connect two nodes with an optional label
`layout_idea_flow`	Write	Auto-arrange all nodes in the canvas using dagre (LR or TB direction)
`delete_idea_flow_node`	Delete	Remove a node and all its connected edges
`delete_idea_flow_edge`	Delete	Remove a connection between two nodes

Knowledge Graph

Tool	Read / Write	Description
`get_knowledge_graph`	Read	Full workspace relationship graph; scope by projectIds; `includeAuto` flag for auto-discovered relationships
`get_neighbors`	Read	N-hop neighbourhood around any node (depth 1–3). More efficient than loading the full graph.