# ctxfile/ctxfile [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/ctxfile/ctxfile  
**GitHub Stars:** 4  
**npm Downloads (last month):** 861  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ctxfile-ctxfile

## Description
Local-first MCP server that snapshots your project's working state — files, git, plan, and decisions — into one structured context object and hands it to any MCP client in a single call. Save a session in one agent, continue it in another. Zero network calls by default; read-only over your project. Works with Claude Code, Cursor, and any MCP client. npx -y ctxfile

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ctxfile": {
    "command": "npx",
    "args": ["-y","ctxfile"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/ctxfile-ctxfile/readme_