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 37 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

Notes

Tool	Read / Write	Description
`get_note`	Read	Full markdown content, linked IDs, metadata, and `version` counter of a note by ID
`search_notes`	Read	Full-text search across notes. Empty query returns all notes.
`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
`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` and `version` counter
`list_ready_tasks`	Read	Only unblocked, active tasks — use this to find work that can start now
`search_tasks`	Read	Full-text search across task cards. Empty query returns all tasks.
`create_task`	Write	Create a task card in a column
`update_task`	Write	Update a task's fields. Pass `archived: true/false` to archive or restore. Pass `blockedBy` to add a blocker, `unblockFrom` to remove one.
`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
`delete_task`	Delete	Permanently delete a task card. Cannot be undone.

Projects

Tool	Read / Write	Description
`upsert_project`	Write	Create or update a project. Omit `projectId` to create (auto-creates 5 default columns); provide `projectId` to update existing fields.
`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.

Tool	Read / Write	Description
`create_tag`	Write	Create a workspace tag with a name and hex colour

Codebase

Tool	Read / Write	Description
`codebase_reindex`	Write	Scan and semantic-index a codebase folder. Updates the SQLite cache of file paths, classes, functions, methods, docstrings, and call dependencies.
`codebase_search_symbols`	Read	Search for classes, functions, methods, interfaces, or structs by name or docstring query. Optional `folder` and `limit` parameters.
`codebase_get_symbol_definition`	Read	Lookup the definition signature, line numbers, and docstring of a symbol by its exact name.
`codebase_get_references`	Read	Find incoming references and outgoing dependencies (call graph) for a given symbol name.
`codebase_get_file_symbols`	Read	List all classes, functions, methods, interfaces, or structs defined in a specific file path.

Agent workflow tip

Call get_cairn_context once at session start — it returns all workspace/project/column IDs and conventions in one call. Use list_ready_tasks to get only tasks with no pending blockers. Use search_notes or search_tasks with an empty query to list everything.

Task dependencies

Use update_task with blockedBy to mark a task as blocked by another in the same project. Circular dependencies are rejected automatically. A blocker is treated as resolved as soon as it moves to a done column or is archived. Use unblockFrom to remove a dependency explicitly.

IDs are stable

Note and task IDs are stable across sessions. Fetch them once and reuse them for subsequent tool calls within the same session.

← Insights

PRD Generator →