The Cairn agent (MCP server + hooks)

mcp-name: io.github.cybort360/cairn-mcp

This folder is the piece that runs on your machine, not on Vercel. It gives Claude Code a set of Cairn tools (log work, list tasks, weekly summaries, and so on) and, if you want, quietly records what you did after every session. Everything here is a thin HTTPS client over your Cairn cloud account — no local database, no second copy of your data.

What's in here:

• cairn_mcp/ — the Python package, published to PyPI as cairn-mcp:
  • server.py — the MCP server. Eleven tools (work_log_add, task_create, daily_summary, …).
  • client.py — the tiny stdlib HTTP client the server and hooks share. Reads your token, talks to the API.
  • session_logger.py — a SessionEnd hook. Turns a finished Claude Code session into one work-log entry.
  • file_logger.py — a PostToolUse hook. Records a file-activity event whenever Claude writes or edits a file.
• pyproject.toml — packaging metadata. One dependency, mcp[cli]; one console script, cairn-mcp.
• .mcp.json, hooks/hooks.json, .claude-plugin/ — the Claude Code plugin wiring.

Easiest: install as a plugin

If you're on Claude Code, skip the manual steps below — this repo is also a plugin marketplace. Two commands from inside Claude Code:

/plugin marketplace add https://github.com/cybort360/cairn
/plugin install cairn@cairn

That registers the cairn MCP server and both auto-logging hooks for you; there's no clone, no venv, and no claude mcp add. One prerequisite: the plugin runs the server through uv, so you need uv on your PATH (curl -LsSf https://astral.sh/uv/install.sh | sh). uv pulls mcp[cli] on its own, so you never manage a Python env.

You still need to drop your token in once — see step 2 of the manual install for where to get it:

printf '%s' 'PASTE_YOUR_TOKEN' > ~/.cairn_token && chmod 600 ~/.cairn_token

From PyPI (any MCP client)

Not on Claude Code, or want the server without the plugin? The package is on PyPI, so uv can run it with nothing to clone or install:

claude mcp add cairn --scope user -- uvx cairn-mcp

uvx cairn-mcp is the command any MCP client can point at; uvx fetches the package and its deps on first run. Save your token first (see step 2 below). For a different client, use its own config — the command is the same.

Manual, from source

For when you'd rather not use uv at all. You need Python 3.10+ and the Claude Code CLI.

1. Clone and install the package into a venv.

git clone https://github.com/cybort360/cairn.git
cd cairn/agent
python3 -m venv .venv
.venv/bin/pip install .

That puts a cairn-mcp console script in .venv/bin/.

2. Get your API token. Sign in at the Cairn web app, open the account menu, and copy your API token. Save it where the client looks for it:

printf '%s' 'PASTE_YOUR_TOKEN_HERE' > ~/.cairn_token
chmod 600 ~/.cairn_token

(You can set CAIRN_TOKEN in the environment instead if you'd rather not write a file. The client checks CAIRN_TOKEN first, then ~/.cairn_token.)

3. Register the server with Claude Code. Point it at the console script. --scope user makes the cairn tools available in every project, not just this one:

claude mcp add cairn --scope user -- "$(pwd)/.venv/bin/cairn-mcp"

4. Check it connected.

claude mcp list

You want to see cairn: … ✔ Connected. Inside a session the tools show up as mcp__cairn__work_log_add, mcp__cairn__task_list, and the rest.

That's the whole install. The hooks below are optional.

Optional: auto-logging hooks

The plugin install already wires these up. Set them by hand only if you went the manual route. The two hooks make Cairn fill itself in without you calling a tool: session_logger writes one entry summarizing each session when it ends; file_logger notes every file Claude touches. Both fail silently — a dropped network call or a missing token never interrupts your work. They use only the standard library, so plain python3 runs them; no mcp needed.

Wire them into Claude Code's settings (~/.claude/settings.json for all projects). The commands run the package modules, so they need cairn_mcp on the path — cd into wherever you cloned ($HOME/cairn/agent assumes ~/cairn; adjust it):

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$HOME/cairn/agent\" && python3 -m cairn_mcp.session_logger 2>/dev/null || true",
            "timeout": 15,
            "statusMessage": "Logging session to Cairn"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$HOME/cairn/agent\" && python3 -m cairn_mcp.file_logger 2>/dev/null || true",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

A hard kill (crash, power loss, kill -9) skips the SessionEnd hook, so that one session won't be logged. Everything else — the normal exit, /clear, /logout, Ctrl-D — fires it.

Pointing at a different backend

By default the client talks to production. Override it with CAIRN_API_URL if you're running the web app locally or against a staging deploy:

export CAIRN_API_URL="http://127.0.0.1:8765"

The MCP server reads it the same way, so set it in the claude mcp add environment (-e CAIRN_API_URL=…) if you want the tools pointed somewhere other than prod.