English Français العربية

Cairn

Official registry Developer tools

Log Claude Code work sessions, file edits, and tasks to your Cairn account.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package cairn-mcp
Claude Code 
claude mcp add cairn -e 'CAIRN_TOKEN=<your cairn_token>' -e 'CAIRN_API_URL=https://cairn-octanes-projects.vercel.app' -- uvx cairn-mcp==0.1.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "cairn": {
            "command": "uvx",
            "args": [
                "cairn-mcp==0.1.2"
            ],
            "env": {
                "CAIRN_TOKEN": "<your cairn_token>",
                "CAIRN_API_URL": "https://cairn-octanes-projects.vercel.app"
            }
        }
    }
}

Environment variables

  • CAIRN_TOKEN secret Your Cairn API token, copied from the web app account menu. If unset, the server reads it from ~/.cairn_token.
  • CAIRN_API_URL Base URL of the Cairn API. Defaults to production.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Cairn
  2. How it's built
  3. Local development
  4. Deployment
  5. The agent side
  6. Design notes

Cairn

A work tracker that remembers what you did. It captures your coding sessions, the files you touch, tasks moving from pending to done, and project notes, then keeps them in one place with daily and weekly rollups. The name is the pile of stones that marks a trail.

Cairn runs as a multi-tenant web app on Vercel with a Neon Postgres database. Each account signs up, logs in, and only ever sees its own data.

How it's built

The whole server is the Python standard library plus one dependency (psycopg). No framework.

  • api/index.py — the Vercel serverless entrypoint. Vercel's Python runtime treats it as a catch-all, so every request lands here.
  • lib/handler.py — routing. The same BaseHTTPRequestHandler runs three ways: the Vercel function, the local dev server, and the tests.
  • lib/data.py — every SQL statement, each one scoped by user_id.
  • lib/db.py — Neon connection (pooled endpoint) plus small query helpers.
  • lib/auth.py — PBKDF2 password hashing, sessions, and token resolution.
  • lib/limits.py — signup/login rate limiting and per-account quota caps, both backed by Postgres.
  • lib/assets.py — the single-page app and favicon, embedded as base64 so they ship inside the function bundle. Generated by build_assets.py; re-run it after editing static/.

Local development

You need a Postgres to point at. A throwaway one in Docker works:

docker run -d --name cairn_pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=cairn -p 5432:5432 postgres:16-alpine
python3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'
export DATABASE_URL="postgres://postgres:pw@127.0.0.1:5432/cairn"
.venv/bin/python dev.py --init    # create the schema, then serve on :8765

Tests run against that same database:

.venv/bin/python tests/smoke.py        # core CRUD + isolation
.venv/bin/python tests/test_limits.py  # rate limiting + quotas
.venv/bin/python tests/test_sp3.py     # file activity + filtered lists

Deployment

Pushing to main deploys to production through the Vercel GitHub integration. DATABASE_URL and the other Neon variables come from the Vercel ↔ Neon integration; the app reads the pooled connection string. Schema changes go on with initdb.py against the direct (unpooled) URL.

The agent side

The agent/ folder is the MCP server and two Claude Code hooks that run on your machine. They talk to this API over HTTPS using your account's token, so anything Claude Code does flows into your Cairn account. The server gives Claude a set of cairn tools; the hooks log sessions and file edits on their own.

On Claude Code the quickest install is the plugin — this repo doubles as a plugin marketplace (.claude-plugin/marketplace.json):

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

That wires up the MCP server and both hooks; you just save your token to ~/.cairn_token (it needs uv on your PATH). The manual route — clone, venv, claude mcp add — is in agent/README.md. The web app deploy ignores agent/; it's client-side only.

Design notes

Each sub-project that built Cairn has a spec under docs/superpowers/specs/: the cloud core, the auth hardening, and the local agent cutover. Read those if you want the reasoning behind a decision rather than just the code.

Frequently asked questions

What is Cairn?

Log Claude Code work sessions, file edits, and tasks to your Cairn account.

How do I install Cairn?

It runs on your machine. In Claude Code: claude mcp add cairn -e 'CAIRN_TOKEN=<your cairn_token>' -e 'CAIRN_API_URL=https://cairn-octanes-projects.vercel.app' -- uvx cairn-mcp==0.1.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Cairn need an API key?

Yes. It expects CAIRN_TOKEN, which you set in its configuration.

Is Cairn open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Cairn?

It is published by cybort360. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.