Cairn MCP server

Cairn

A local-first, open-source harness for organizing your files with an AI agent.

Point Claude Code, Codex, Cursor — any MCP client — at a folder, and your agent gains a full file-organization toolset: list, read, search, grep, edit, move, tag, import documents, and semantically retrieve. No account, no cloud, no UI required. Your files never leave your machine.

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Then ask your agent to "organize this folder and tag everything" — it will, using tools that run locally over your own files.

A cairn is a stack of stones that marks a trail. This one keeps your files in

order and shows the way through them.

Quickstart (2 minutes)

If you use Claude Code, setup is one command — the only prerequisite is uv, which provides uvx:

# 1. Install uv if you don't have it (provides uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Add Cairn to Claude Code, pointed at a folder you want organized
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Reopen Claude Code and ask:

"Organize this folder and tag everything."

Cairn's tools run locally over your files — reads happen freely, and any move/rename/edit asks for confirmation first. The first run auto-downloads the package (~5s); no clone, no build, no account.

[!TIP]

Point --workspace at a copy of some notes for your first run — Cairn can

move, rename, and edit files.

Using Codex? Same one-command flow (then run /mcp in a session to confirm):

codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Using Cursor or another MCP client? Same package, JSON config:

{ "mcpServers": { "cairn": { "command": "uvx",
  "args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } }

~ is expanded by Cairn, so ~/Documents/notes works in the CLI and in config files alike.

Just want to poke at it, no agent?

uvx cairn-cli --workspace ~/Documents/notes tree

Why a harness

The agent-harness ecosystem converged on a clear pattern: the model and the agent loop are commodities supplied by the client (Claude Code, Codex, OpenCode). The durable value is the tools and the local data. So Cairn ships tools, not an agent — the client provides the loop, the approval prompts (driven by our tool annotations), and the chat. Cairn is just the local file-organization toolset that snaps into whatever harness you already use.

Architecture

Everything is a thin adapter over one standard-library core, so the faces can never drift.

core/          cairn-core — the engine (stdlib only): the .uni document format,
               file operations, tags, retrieval; optional document ingestion
               (docx/pdf/pptx/xlsx/md) and embeddings-based search.
mcp-server/    cairn-mcp-server  — MCP server: 26 tools with read-only/destructive
               annotations, resources, and prompts.        ← the flagship
cli/           cairn-cli  — scriptable CLI, a local HTTP API (`serve`),
               and an `mcp` launcher.
web/           cairn-web  — optional zero-build local web UI
               (browse / edit / view / tag / search).

Use it

In Claude Code / Codex / Cursor (primary):

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
# with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ...

The server exposes read-only tools (list, read, search, grep, retrieve) that the client runs freely, and destructive tools (move, delete, edit) that it confirms first — driven by MCP tool annotations, so you get approval prompts with no UI of ours.

As a CLI:

uvx cairn-cli --workspace ~/Documents/notes tree
uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning"

With the optional web UI:

Shortened. The full README is on GitHub.