one-context-mcp

One local MCP server that gives Claude, Cline, Codex, and other AI tools the same project memory.

one-context-mcp stops the repeated setup explanation every time you switch AI tools. It stores project context locally in a small SQLite database and exposes it through MCP tools that every connected assistant can read and update.

• PyPI package: one-ctx
• Main CLI command: one-context
• Alternate CLI commands: ctx, one-ctx
• GitHub repo: m4vic/one-context-mcp
• Default merge mode: local rules only, no model and no API key

Quick Install

Add this to Claude Desktop, Cline, Codex, or any MCP client:

{
  "mcpServers": {
    "one-context": {
      "command": "uvx",
      "args": ["--from", "one-ctx", "one-context", "stdio"]
    }
  }
}

Then fully restart the MCP client.

Full setup instructions are in INSTALLATION_GUIDE.md.

Why It Exists

Every coding assistant has its own short-term context. When you move from Claude to Cline, from Cline to Codex, or from one IDE session to another, you usually explain the same project again:

This is a FastAPI backend, PostgreSQL is the database, src/main.py is the entry point, we just changed auth, and next we need rate limiting.

one-context-mcp makes that explanation persistent and shared.

Architecture

graph TD
    classDef rootNode fill:#0d1117,stroke:#58a6ff,stroke-width:3px,color:#c9d1d9,font-size:16px,font-weight:bold;
    classDef aiNode fill:#161b22,stroke:#3fb950,stroke-width:2px,color:#c9d1d9,font-size:14px;
    classDef bucketNode fill:#21262d,stroke:#8b949e,stroke-dasharray: 5 5,color:#c9d1d9;
    classDef localNode fill:#1f2937,stroke:#f59e0b,stroke-width:2px,color:#f9fafb;

    A([one-context MCP Server]):::rootNode
    DB[(Local SQLite DB)]:::localNode

    C1[Claude Desktop]:::aiNode
    C2[Cline / VS Code]:::aiNode
    C3[Codex]:::aiNode
    C4[Other MCP Clients]:::aiNode

    B1[(WHAT\nProject scope)]:::bucketNode
    B2[(DONE\nHistory and decisions)]:::bucketNode
    B3[(NOW\nCurrent work)]:::bucketNode
    B4[(MAP\nImportant files)]:::bucketNode
    B5[(NOTES\nUser messages)]:::bucketNode

    C1 <-->|ctx_get / ctx_update| A
    C2 <-->|ctx_get / ctx_update| A
    C3 <-->|ctx_get / ctx_update| A
    C4 <-->|MCP tools| A

    A --- DB
    DB --- B1
    DB --- B2
    DB --- B3
    DB --- B4
    DB --- B5

Everything is local by default. No account, no cloud service, no vector database, and no LLM API call is required.

First Use

Use a stable project name. For example, use asrt every time you refer to the ASRT project.

Ask your assistant:

Use one-context. Link project asrt to F:\ASRT, then load context.

At the end of a work session:

Update one-context for project asrt with what we changed, what is done, what is next, and important files.

You do not edit MCP config when switching work folders. Link each project once with ctx_link(project, repo_path).

What Gets Stored

MAP entries are normalized and deduplicated. When a project is linked to a repo_path, file tracking is scoped to that repo so context from different projects does not get mixed.

MCP Tools

ctx_get also accepts view: "brief" to return only the recent slice of DONE when the calling session is low on context.

CLI Reference

ctx status [project]          # View current context or list projects
ctx init <project> --path .   # Create/link project to repo path
ctx search <query>            # Search across projects and history
ctx export <project> -o f.json   # Backup one project (--all for everything, --format md for readable)
ctx import f.json             # Restore/merge an exported backup
ctx reset <project>           # Clear a project's context
ctx delete <project>          # Permanently delete a project
ctx list                      # List all projects
ctx serve --port 7337         # Start HTTP/SSE server (localhost only by default)
ctx stdio                     # Start stdio MCP server

Backup & Portability

Your entire context lives in one SQLite file (~/.ctx/ctx.db). To back it up, commit it to a repo, or move machines:

ctx export myproject -o context-backup.json   # per-project backup
ctx export --all -o all-context.json          # everything
ctx import context-backup.json                # merge into existing (safe, idempotent)
ctx import context-backup.json --mode replace # overwrite buckets

Any MCP client can do the same via the ctx_export / ctx_import tools.

Security

• stdio mode (the default setup) has no network surface.
• ctx serve binds localhost only by default (changed in 0.4.0; previously 0.0.0.0).
• To expose HTTP mode on a network, set a token first: CTX_AUTH_TOKEN=<secret> ctx serve --host 0.0.0.0. Clients must then send Authorization: Bearer <secret>. Without the token the server warns loudly.
• With auth enabled, /health hides the tool list and CORS is restricted to localhost origins.

Documentation

• Installation Guide
• PyPI package
• GitHub Releases

License

MIT

Built to end context amnesia across AI tools.