Ctxfile

What the ctxfile/ctxfile MCP server does

The ctxfile/ctxfile MCP server packages a project's working state into a context object that another MCP-compatible agent can load. Its snapshot can include plan documents, selected project files constrained by a token budget, Git state, and optional Notion or local-language-model information. The default workflow is local: project data stays on the machine, and the core server does not modify the repository or Git state.

It also preserves conversational handoffs. save_session records an agent-written summary, while continue_thread combines that history with later context and labels its provenance. Threads provide durable names for work such as a campaign or feature, and a handoff can require a complete package containing state, decisions and rationale, open items, and gotchas.

How it works

An MCP client starts the server over stdio. The agent can then request get_context to receive one structured snapshot, or use the session and thread operations to save and retrieve work across agents. ingest_context provides a schema-checked input path for clients that do not have a native parser; the prompt acts as the format adapter.

The server can also create an exported, static artifact with ctxfile export. That artifact is intended for hosted coding agents, CI, or other environments that cannot access the local project. The .ctxfile format is documented as an open convention.

For local inspection, ctxfile ui starts a dashboard on 127.0.0.1. Optional Sync uses an end-to-end encrypted vault through a relay that can be self-hosted. The README describes Argon2id key derivation and XChaCha20-Poly1305 encryption for stored blobs.

Setup and configuration

Install the ctxfile/ctxfile MCP server in a client using npx -y ctxfile. Node.js 20 or newer is required, with Node.js 22 or newer on Windows. Claude Code can register it with claude mcp add ctxfile -- npx -y ctxfile; Cursor can use the equivalent stdio entry in .cursor/mcp.json or the global configuration. Other standard MCP clients can run the same command.

Claude Desktop users on Apple Silicon can install the provided macOS .mcpb bundle. Windows and Intel Mac users should configure the stdio server in claude_desktop_config.json instead. Running ctxfile init adds agent instructions for automatic checkpoints, including a Cursor rule and managed instruction blocks for supported agent harnesses.

Tools and capabilities

• Snapshot files, plans, Git state, and selected context with get_context.
• Save summaries and resume work with save_session and continue_thread.
• Maintain named threads and structured takeover packages.
• Ingest context through a schema-enforced MCP operation.
• Export repo-safe context for agents without local filesystem access.
• Browse snapshots and Git information through the local dashboard.

Limitations and notes

The default implementation is read-only over the project and makes no network calls. Secret-like values are redacted before snapshots are created, while .env files, key files, and credential files are not read. Notion, local Ollama summarization, and Sync require explicit configuration and are exceptions to the local-only default.

The ctxfile/ctxfile MCP server does not automatically make every external chat client local-aware. Web chat workflows use the optional Sync connector or an exported context envelope pasted into the chat. The repository is Apache-2.0, while the separate Pro add-on is closed and adds additional connectors and features.