Cairn MCP server
Commit Nov 13, 2026An AI-powered workspace that lets external agents read and write notes, tasks, and project data via a local MCP server.
Also known as ddutchie/cairn
- Stars
- 19
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Cairn MCP?
Cairn is an AI-powered workspace that lets external agents read and write notes, tasks, and project data via a local MCP server.
Summary generated from the project's README
About Cairn MCP server
Managing project documentation and task tracking through external AI agents is possible with Cairn. This local-first desktop application functions as a workspace for markdown notes and kanban boards, allowing users to point the software directly at existing Obsidian vaults. Because it stores notes as plain markdown files and project data in a local SQLite database, it operates entirely without a cloud backend or required accounts.
The included MCP server exposes your workspace to external clients like Claude Desktop or OpenCode. By connecting the standalone stdio binary, agents can use approximately 20 tools to read and write notes, manage tasks, interact with the Idea Flow canvas, and query the knowledge graph. Users can configure the server to work with any OpenAI-compatible endpoint, including local providers like Ollama or LM Studio, ensuring that all data remains on your machine.
What you can do with it
- 1Automated project documentationAn AI agent can describe a feature and then write a complete PRD directly into your project notes.
- 2Synchronized task managementA coding agent can automatically move kanban cards through different workflow stages as it completes work.
- 3Contextual knowledge retrievalDevelopers can use external agents to search through all existing notes and tasks within a workspace.
- 4Automated session loggingThe system can capture bugs and decisions discovered during a coding session and save them as new notes.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableddutchie/cairn is public and reachablegithub.com/ddutchie/cairn ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/ddutchie/cairn ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCairn
A calm, local-first workspace for notes, project tracking, and visual idea mapping — with an AI assistant and MCP server built in.
Overview
Cairn is a desktop app (Electron + Next.js) that combines markdown notes with a kanban board. It is fully compatible with Obsidian vaults, allowing you to point a workspace directly to any existing Obsidian folder. Notes are saved as plain .md files directly in your vault; project and task data lives in a local SQLite database alongside them. No accounts, no cloud, no backend. An embedded AI assistant and a standalone MCP server let AI agents read and write your workspace directly.
Features
- Projects — Multiple projects inside a workspace, each with notes and a board
- Notes — Split-pane markdown editor (write on the left, preview on the right)
- AI text actions — Select any text in a note → floating toolbar → Rephrase, Summarize, Expand, Fix Grammar, Change Tone, or custom prompt
- Kanban board — Drag-and-drop cards across columns with priority indicators; Archive All Done button clears the Done column in one click; Archive view (Board / Archive toggle) shows all archived tasks in a searchable grid with restore and delete actions
- Drag notes into folders — Drag any note in the sidebar directly onto a folder row to move it; a "Move to root" drop zone appears while dragging
- Linked context — Notes and cards reference each other bidirectionally
- Global search — Instant full-text search across all notes and tasks (
⌘Kor⌘⇧F) - AI chat — Integrated assistant with live project context; reads and writes your data (
⌘/) - Interactive PRD generation — Describe what you want to build; the agent asks clarifying questions then writes and saves a full PRD to your notes
- Idea Flow — Freeform node canvas per project (
⌘5by default): ideas, note/task refs, groups, URLs, AI summaries — connected with labelled edges - MCP server — Exposes your workspace to external AI agents (OpenCode, Claude Desktop, etc.) via the Model Context Protocol
- Cairn Agent — Native coding agent (Agent view) with board and notes integration: moves tasks, writes session notes, captures discovered work; delegates to subagents for deep sub-tasks; Plan / Execute mode toggle; interactive tool confirmations with mobile-desktop sync; automatic retry on transient API errors; automatic context compaction for long sessions (
/compacton demand); context usage ring; works with any OpenAI-compatible endpoint. Runs on Cairn's own agent engine — see Architecture. - Agent workspace — Three-pane view for running external AI coding agents (Claude Code, OpenCode, Aider, or any CLI) connected to project tasks; file tree, multi-file CodeMirror 6 editor, xterm.js terminal, and git diff viewer
- Knowledge Graph — Workspace-wide graph of every note, card, project, and tag; Force-directed and Radial tree layouts; auto-discovered relationships
- Insights — Analytics view: Ridgeline joy plot, Beeswarm, Bullet health bars, Sankey pipeline flow, Timeline, Matrix heatmap, Table, Semantic map (notes plotted by similarity)
- Font scaling — Five-step UI font size preference (XS–XL, default M) in Settings → General
- Obsidian Vault Compatibility — Works side-by-side with Obsidian vaults; renders standard double-bracket embeds (
![[image.png]]), uploads files to custom attachment folders, resolves local media via sequential-fallback protocol, and merges YAML frontmatter non-destructively - Local-first — Notes as
.mdfiles, project data in SQLite; no network required - Dark mode — Calm, focused aesthetics
Screenshots
Getting started
Prerequisites
- Node.js 20+
- macOS (arm64 build provided; Windows/Linux untested)
Install and run in development
git clone https://github.com/ddutchie/cairn
cd cairn
npm install
npm run rebuild # build better-sqlite3 native binaries for Electron + system Node
npm run compile # compile Electron main process + bundle MCP server
npm run dev # start Cairn (Next.js + Electron)
Build the packaged app
npm run build:mac # macOS DMG (arm64 + x64)
npm run build:win # Windows NSIS installer (x64 + arm64)
npm run build:linux # Linux AppImage (x64 + arm64)
npm run build:all # All three platforms
Output goes to dist-app/.
Note: Re-run
npm run rebuildafter any Electron version bump. It builds native binaries for three ABIs (Electron, Node 22/MCP, system Node/vitest) and bundles the MCP server into a self-contained binary viascripts/build-mcp-binary.js.
AI chat setup
Configure the AI endpoint in Settings → AI (tabs: Chat, Coding Agents, MCP; no restart needed):
| Setting | Default | Notes |
|---|---|---|
| Base URL | https://api.openai.com |
Any OpenAI-compatible endpoint |
| Model | gpt-4o-mini |
Any model name the endpoint accepts |
| API Key | (blank) | Not required for local endpoints |
Quick presets — one click to switch between OpenAI, Ollama (localhost:11434), and LM Studio (localhost:1234). Local servers don't need an API key.
[!NOTE] Proxy & Gateway Timeouts (504): If pointing to an API gateway proxy or reverse proxy (e.g., nginx), long synchronous non-stream requests can trigger connection timeouts (returning a
504 Gateway Time-out). All completion requests in Cairn (including chat tool loop and context compaction) stream internally to keep the connection active.
Cairn Agent
Cairn includes a native coding agent that runs directly inside the app — no external CLI binary required. It is accessible from the Agent view (⌘5) by choosing Cairn Agent in the spawn modal.
The agent runs on Cairn's own engine (pi-ai model streaming): a shared engine drives the model↔tool loop, session persistence, approvals, subagents, background jobs, and context compaction — Cairn contributes its workspace tools, board-aware system prompt, and renderer bridges. See Architecture.
What makes it Cairn-specific
Unlike a general coding agent, the Cairn Agent is a first-class participant in your project:
- Board integration — when you attach a task at spawn time, the agent moves it to In Progress immediately and to Review (or Done) when it finishes
- Automatic notes — findings, decisions, and bugs discovered during a session are written to project notes via
ensure_note(idempotent — no duplicates on re-run) - Session summary — a summary note is created at the end of every session documenting what changed and what needs follow-up
- Out-of-scope capture — issues found beyond the current task are automatically added to the board as new tasks
Plan Mode
Launch the agent in Plan Mode to produce a spec before writing any code. The agent reads your codebase (read-only tools only) and writes a structured PRD note to your project. An Approve Plan button in the chat header then promotes the session to Execute Mode, injecting the full PRD as context for the coding run.
Subagents
The agent can delegate contained sub-tasks to a fresh subagent via the subagent tool (one-shot) or delegate (continuable background conversations you can message later). A delegated agent runs with its own session history — only its final answer returns to the parent, keeping the parent context lean for long multi-step tasks. The subagent trace renders inline and collapsible in the chat UI.
Context usage ring
A small ring in the agent pane header shows how full the model's context window is after each step. Configure the limit for your model in Settings → AI → Coding Agents → Context window (presets: 8k / 32k / 128k / 200k).
When usage reaches 80% the agent automatically compacts older context — the status bar shows "Compacting context…" while this is in flight. Type /compact in the chat input to trigger compaction on demand at any time. If a transient API error occurs, the status bar shows a countdown ("Transient error — retrying (1/3) in 8s…") and the agent retries automatically.
MCP server
Cairn ships a standalone stdio MCP server as a self-contained binary (dist-mcp/cairn-mcp), built with @yao-pkg/pkg. It connects directly to the same SQLite database as the app — writes are reflected in the UI in real time via WAL polling.
Connect from OpenCode
Add to opencode.json in your project root:
{
"mcp": {
"cairn": {
"type": "local",
"command": ["/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"],
"enabled": true
}
}
}
Connect from Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"cairn": {
"command": "/Applications/Cairn.app/Contents/Resources/app.asar.unpacked/dist-mcp/cairn-mcp"
}
}
}
The exact paths above are generated automatically in Settings → AI → MCP — copy them from there.
Available MCP tools
The MCP surface is derived from the same schemas the in-app agents use (electron/lib/tool-schemas.ts — everything except chat-only tools such as ask_questions and suggest_connections), across notes, tasks, projects, Idea Flow, the knowledge graph, and codebase search — one tool per intent (about 20 in all). The authoritative live list is always in the app under Settings → AI → MCP, which shows every tool with its read/write/delete category — this file does not duplicate that list so it can't rot.
Agent tip: call
get_contextat the start of a session for all workspace/project/column IDs. Usesearch_taskswithfilter: "ready"when you want to know what work can actually start — it skips anything blocked by an unresolved dependency. Useupdate_taskswithblockedBy/unblockFromto manage task dependencies.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
⌘K |
Open global search |
⌘⇧F |
Global search (any view) / File search in Agent view sidebar |
⌘F |
In-context search — find/replace in Note or Agent editor; filter in Notes list, Board, or Knowledge Graph |
⌘N |
New note (switches to Notes view) |
⌘/ |
Toggle AI chat |
⌘\ |
Toggle sidebar |
⌘1 / ⌘2 |
Overview / Notes (always) |
⌘3–⌘9 |
Walk the visible views in sidebar order (default: Board, Calendar, Flow, Agent, Graph, Insights, Automations) — hide views in Settings → Sidebar & views to compress the range |
⌘S |
Save file (Agent editor) |
⌘Z |
Undo |
⌘⇧Z / ⌘Y |
Redo |
Esc |
Close modal / search / filter bar |
Architecture
Two processes share a single SQLite database (WAL mode):
- Renderer (
src/) — React/Next.js. All data flows through IPC viawindow.electron.*; never touches the DB or filesystem directly. - Main process (
electron/) — Node.js. Owns SQLite, file I/O, the agent engine, and PTY sessions for coding agents. IPC handlers are split into per-domain registrars (db-handlers.ts,flow-handlers.ts,chat.ts,session-runtime-handlers.ts,runtime-handlers.ts, etc.) orchestrated byhandlers.ts. - Agent engine (
electron/agent/) — one engine drives chat, coding and automation turns: model↔tool loop (pi-ai), JSONL sessions, approvals (decide()policy), subagents, background jobs, terminals, skills, auto-compaction, and an OS sandbox for shell commands. Cairn contributes its workspace tools, the board-aware coding prompt (lib/coding-session-prompt.ts) and renderer bridges (ipc/engine-bridge.ts). App I/O crosses into the engine only through the HostStore seam (host-store.ts). Seedocs/plans/agent-engine-design.md. - MCP server (
electron/mcp-server.ts) — self-contained binary; connects external agents to the same DB via WAL polling. SQL query helpers are shared with the Electron main process viaelectron/db/queries.ts(single source of truth).
Notes are plain .md files (YAML frontmatter); SQLite is the read/search cache. Writes are atomic (.tmp rename). A chokidar watcher syncs external edits at runtime. notes and task_cards carry a version integer; MCP write tools accept expectedVersion for conflict detection.
For the full architecture reference see CONTRIBUTING.md. AI coding agents should read AGENTS.md for conventions tuned to LLM context windows.
Testing
npm test # full gate: licenses + features + compile + unit & integration (Vitest)
npm run test:watch # watch mode
npm run test:coverage # coverage report
npm run test:e2e # E2E smoke tests — headless Chromium, no Electron required
npm run test:e2e:ui # Playwright UI mode
npm run test:e2e:headed # headed for local debugging
Unit/integration tests (electron/**/*.test.ts) cover SQLite queries, file I/O, MCP tools end-to-end, chat executor tool cases, IPC handlers, and MCP↔chat tool parity. The E2E suite runs against the Next.js dev server with a full IPC mock — covers boot, all 8 views, and sidebar content in ~10s.
Run npm run test:e2e before cutting a release to catch renderer crashes unit tests can't reach.
Tech stack
Platform
| Tool | Role |
|---|---|
| Electron | Desktop shell |
| Next.js 16 | UI framework (App Router, static export) |
| TypeScript | Language |
| esbuild | Bundler (Electron main + MCP binary) |
| vitest | Unit & integration test runner |
| Playwright | E2E smoke tests (browser, no Electron required) |
Data & AI
| Tool | Role |
|---|---|
| better-sqlite3 | SQLite (arch-separated native bindings for Electron + MCP + vitest) |
| gray-matter | YAML frontmatter parsing for note files |
| chokidar | File watcher for external .md edits |
| @earendil-works/pi-ai | Model streaming for the agent engine |
| onnxruntime-node + @huggingface/transformers | Local embeddings for semantic search |
| @modelcontextprotocol/sdk | MCP server |
| Zod | Schema validation |
| nanoid | ID generation |
UI & State
| Tool | Role |
|---|---|
| Tailwind CSS v4 | Styling (CSS custom properties; never raw colour names) |
| Zustand | State management (domain slices: ui, workspace, board, notes, tags, chat, graph, selectors, coding-agents, terminal-sessions) |
| Radix UI | Accessible UI primitives (dialog, dropdown, tooltip, popover, select, context menu) |
| Lucide React | Icons |
| cmdk | Command palette |
| react-day-picker | Date picker |
| date-fns | Date utilities |
| tailwind-merge | Tailwind class merge utility |
Editor & Agent
| Tool | Role |
|---|---|
| CodeMirror 6 | Note editor + Agent file editor (CM6, CSS-hidden-per-tab pattern) |
| @codemirror/search | In-editor find/replace panel (⌘F) |
| node-pty | PTY process spawning (Agent terminal) |
| @xterm/xterm | Terminal emulator (Agent view) |
| @xterm/addon-fit | Terminal auto-resize |
| parse-diff | Git diff parser (Agent diff viewer) |
Visualisation
| Tool | Role |
|---|---|
| @xyflow/react | Node-based canvas (Idea Flow) |
| dnd-kit | Drag and drop (Kanban) |
| D3 v7 | Analytics & graph visualisation (Insights canvases, Radial tree, Force-directed graph) |
| d3-sankey | Sankey pipeline diagram (Insights) |
| @dagrejs/dagre | Graph auto-layout (Idea Flow) |
Markdown
| Tool | Role |
|---|---|
| react-markdown | Markdown preview |
| remark-gfm | GitHub Flavored Markdown |
| remark-breaks | Hard line breaks in markdown |
| remark-math / rehype-katex | Math expression rendering |
| Mermaid | Diagram rendering in notes |
| lowlight | Syntax highlighting in code blocks |
The Settings → About screen in the app shows real installed versions grouped by category (Platform, Data, AI, UI, Editor, Agent, Visualisation) and all open source licenses. These are generated automatically at build time — see below.
Star History
Contributing
Contributions are welcome — bug fixes, features, docs, and tests. See CONTRIBUTING.md for the full guide: dev setup, architecture, coding conventions, and PR checklist.
For security issues please see SECURITY.md rather than filing a public issue.
License
MIT — see LICENSE.
Cairn MCP questions
Is Cairn compatible with Obsidian?
Yes, Cairn is fully compatible with Obsidian vaults, allowing you to point a workspace directly to any existing Obsidian folder and use markdown files.
Does Cairn require a cloud account?
No, Cairn is a local-first application with no accounts, no cloud, and no backend required.