Server data from the Official MCP Registry
Local-first file-organization tools for your AI agent: tag, query, and digest a folder. No cloud.
About
Local-first file-organization tools for your AI agent: tag, query, and digest a folder. No cloud.
Security Report
Cairn is a well-structured local-first file-organization MCP server with solid security fundamentals. The codebase demonstrates careful attention to path validation, error handling, and permission scoping. No authentication is required (by design for local-first use), and file operations are appropriately constrained to the configured workspace. Minor code quality observations exist but do not represent security vulnerabilities. Package verification found 1 issue (1 critical, 0 high severity).
7 files analyzed · 9 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
Unverified package source
We couldn't verify that the installable package matches the reviewed source code. Proceed with caution.
What You'll Need
Set these up before or after installing:
Environment variable: CAIRN_WORKSPACE
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-luckyjackluo-cairn": {
"env": {
"CAIRN_WORKSPACE": "your-cairn-workspace-here"
},
"args": [
"cairn-cli"
],
"command": "uvx"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
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
--workspaceat 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:
pip install cairn-cli cairn-web
cairn --workspace ~/Documents/notes serve # → http://127.0.0.1:4177/
The .uni format
A .uni file is a small JSON document — { uuid, content: "<html>", metadata, tags } — with tags stored in the file. A workspace is just a directory: fully
portable, no external database. Source documents (docx/pdf/pptx/…) import into
editable .uni docs; the originals are kept by default.
Local-first & bring-your-own-key
- No account, no login, no cloud sync. The filesystem is the source of truth.
- The default retriever is lexical and needs nothing. Embeddings are opt-in and
bring-your-own-key (any OpenAI-compatible endpoint, including local servers
like Ollama or LM Studio); vectors live in a local SQLite index under
<workspace>/.cairn/and never leave your machine.
Roadmap
Cairn is young. Rough direction, and where help is most welcome:
- More document faces — richer frontmatter support (nested metadata, dates), and round-tripping edits back into imported source formats.
- Smarter digests — summaries that use an embedding model when one is
configured, and saved views (
.cairn/views/*.md). - More retrieval backends — pluggable rerankers; first-class local-model presets (Ollama, LM Studio) beyond the generic OpenAI-compatible path.
- Editor/agent integrations — thin recipes for wiring Cairn into common MCP clients and note-taking setups.
- Packaging — signed releases and a Homebrew formula.
Have a use case that doesn't fit? Open an issue or start a discussion.
Contributing
Contributions of every size are welcome — see CONTRIBUTING.md
for the project layout, dev setup, and how to add a tool. Good first issues are
labeled good first issue.
Develop
make setup # uv venv (3.11) + editable install of all packages + extras
make test # run the suite
make serve WORKSPACE=~/Documents/notes # web UI
License
MIT — see LICENSE.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Fetch
Freeby Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
MarkItDown
Freeby Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption