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

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 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
ctx stdio                     # Start stdio MCP server

Documentation

• Installation Guide
• PyPI package
• GitHub Releases

License

MIT

Built to end context amnesia across AI tools.