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:\Program Files\Cairn\resources\app.asar.unpacked\dist-mcp\cairn-mcp.exe

Linux

./Cairn.AppImage --appimage-extract
squashfs-root/resources/app.asar.unpacked/dist-mcp/cairn-mcp-linux-x64

Cairn ships for Linux as an AppImage, which mounts itself at a temporary path on every launch, so extract it once (--appimage-extract) and point your client at the extracted binary (cairn-mcp-linux-arm64 on ARM). Pass CAIRN_DB_PATH if it can't find your workspace.

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

Workspace detection and running while the app is closed

cairn-mcp is a standalone process with its own bundled Node runtime and SQLite — it does not need the Cairn app to be running, so agents can read and write your workspace while Cairn is closed. On start it finds the workspace in this order:

1. The CAIRN_DB_PATH environment variable, if set — either the workspace folder or the cairn.db file itself.
2. The workspace folder the app last used (read from its workspace-config.json).

If no workspace is found, the server exits with a message telling you to open Cairn once to choose a workspace folder, or to set CAIRN_DB_PATH. The server never creates or migrates the database — the app owns the schema — so open Cairn at least once against a workspace before connecting. If you switch workspace folders in the app, a running cairn-mcp notices and follows the change within about a second; no restart needed.

To point a client at a specific workspace, add an env block to its config:

{
  "mcpServers": {
    "cairn": {
      "command": "/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp",
      "env": { "CAIRN_DB_PATH": "/path/to/your/workspace" }
    }
  }
}

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 shows a native OS notification (when the app is not focused) within about a second. 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 and Idea Flow tools.

Tool reference

The Cairn MCP server exposes 19 tools. Since v3.1.3 the toolset is consolidated: one tool per intent, with options (mode, filter, action, type) in place of near-duplicate tools. The server also exposes two read-only MCP resources, cairn://workspaces and cairn://projects.

Context and search

Notes

Tasks

Projects and deletion

Idea Flow

Knowledge Graph

Writing style

Codebase