The context-mcp server provides persistent memory, a codebase knowledge graph, and file/git operations for AI coding assistants.
Persistent Memory & Context Management
Save, retrieve, update, and delete context entries (decisions, bugs, notes, configs) across sessions and projects.
Search entries using keyword-first with semantic fallback; auto-deduplication and compaction included.
Codebase Knowledge Graph (CodeGraph)
codegraph_build: Parse a codebase via tree-sitter AST across 16 languages to build a knowledge graph of functions, classes, imports, and call edges — no API key required.
codegraph_query: Ask natural-language structural questions or look up specific nodes by name (type, location, dependencies, callers).
codegraph_report: Generate a report highlighting god nodes, clusters, and surprising connections.
codegraph_nodes: List all nodes of a given type (class, function, module, file, etc.).
codegraph_path: Find the shortest relationship path between two concepts.
codegraph_affected: Identify the blast radius if a component changes.
codegraph_html: Generate interactive visualizations (force graphs, D3 trees, Mermaid diagrams, Obsidian vaults).
File & Git Operations (HTTP/online mode)
File ops: read_file, write_file, patch_file, create_dir, list_dir, delete_file — sandboxed to the project root.
Git ops: git_status, git_diff, git_log, git_commit, git_push, git_pull, git_branch, git_stash, git_reset, git_show (requires explicit enablement).
Multi-Platform Support
Auto-configure MCP for Claude Code, Cursor, VS Code Copilot, Gemini CLI, Codex, Windsurf, Claude.ai, and ChatGPT.
Run as an HTTP server (ctx online) with OAuth authentication for web-based AI clients.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@context-mcp Load my project context and recent decisions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.
One shared context store across Claude Code, VS Code Copilot, Google Antigravity (2.0 / IDE / CLI), Codex CLI, Hermes Agent, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.
Every conversation with an AI assistant starts from zero. The AI re-reads files it already read yesterday, re-discovers architecture it already understood, re-derives decisions that were already made. You repeat context. You paste the same background.
This gets worse as projects grow — reading 20 files to answer "what calls this function?" burns thousands of tokens every time.
Related MCP server: GraphHub
Persistent memory — decisions, bugs, notes, and config saved across sessions, loaded automatically at conversation start
Shared store — ~/.context-mcp/projects/<name>/ per-project on your machine; all AI tools read and write it
ContextGraph — build a knowledge graph of your codebase once, answer structural questions in ~500 tokens instead of ~50,000
Real measured reduction on this project: 162× fewer tokens, 99.38% reduction per conversation.
npm install -g context-mcp-serverRequires Node.js ≥ 18. Installs context-mcp, context-mcp-http, and the ctx CLI.
ContextGraph requires uv (Python runner). Memory tools work without it.
# macOS / Linux
curl -Ls https://astral.sh/uv/install.sh | sh
# Windows
winget install astral-sh.uvRun from your project root:
ctx install --initialThis installs Node.js + Python (ContextGraph) dependencies. Run once after installing the npm package.
Then write MCP config + AI instruction files:
ctx install --allTo install for a specific platform only:
ctx install --claude # Claude Code
ctx install --vscode # VS Code Copilot
ctx install --antigravity # Google Antigravity (2.0 / IDE / CLI)
ctx install --codex # Codex CLI
ctx install --hermes # Hermes AgentFor Codex project installs, ctx install --codex writes:
.codex/config.toml with [mcp_servers.context-mcp] MCP configuration.
AGENTS.md with Context-MCP usage rules for Codex.
.codex/hooks/ pre/post shell hook scripts for project-local Codex sessions.
For web clients (Claude.ai, ChatGPT), start the HTTP server:
ctx online # start in background, prints OAuth credentials + URL
ctx online --restart # force restart
ctx online --port 3200 # different portThis repo is also a self-hosted Claude Code plugin marketplace — an alternative to ctx install --claude that doesn't require cloning or npm-installing anything yourself:
claude plugin marketplace add vibhasdutta/context-mcp
claude plugin install context-mcp@context-mcp-marketplaceor from inside a session: /plugin marketplace add vibhasdutta/context-mcp then /plugin install context-mcp@context-mcp-marketplace. This installs the context-mcp skill, the Bash pre/post-tool-use hooks, and registers the MCP server (still launched via npx context-mcp-server@latest) — everything ctx install --claude writes into ~/.claude/, bundled as one installable unit. ctx install --initial is still required once to install the ContextGraph Python environment.
Both ctx and context are aliases for the same CLI.
ctx # interactive mode (UI)
# Context
ctx list [project] # list entries by tree: graph / context / summary / plans
ctx projects # all projects with graph status + recent entries
ctx search "query" # keyword → semantic fallback search
ctx add # add entry interactively
ctx summary [project] # summarize recent entries
# Delete
ctx delete <id-prefix> # delete one entry
ctx delete project <name> # delete all entries for a project
# Server
ctx online # start HTTP server (idempotent)
ctx online --restart # force stop + restart
ctx settings # view and edit config interactively
# Install
ctx install --initial # install / update Node.js + Python deps
ctx install --all # write config + rules for all platformsFile and git tools are sandboxed to your project root. Pass rootPath when calling context.resume:
{ "action": "resume", "project": "my-app", "rootPath": "/home/user/my-app" }Any file or git operation outside that directory is rejected. Applies to all HTTP-connected clients.
context.resume — loads recent entries, active plans, and graph status; registers rootPath for sandboxing
context.save — store context as note (or compaction for session summaries); categorize with free-form tags
context.get / context.update / context.delete — full CRUD, single or batch
search — keyword-first, semantic fallback
plan — auto-triggered when AI makes any plan; saves a markdown summary to a planDir you specify
Auto-deduplication on save; auto-compact at 20 entries → stored in summary.json
Also called CodeGraph. MCP tools use the
codegraph_*prefix — both names mean the same thing.
Step 1 — Build (once per project, runs locally, no API cost):
codegraph_build(path)Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, call edges, and inheritance. Every node carries a full enriched schema: signature, params, return_type, docstring, side_effect, exported, complexity, last_modified. PageRank scores all nodes by connectivity. Metadata saved to <project>/codegraph-cache/.
Step 2 — Query (instant, forever):
codegraph_arch(path, limit?) → module map: every file, its exports, its imports
codegraph_query(path, question?, node?) → structural question OR single-node lookup (or both)
codegraph_nodes(path, type, token_budget?) → all nodes of a type, sorted by PageRank
codegraph_filter(path, node_type?, exported?, → predicate filter: side_effect, return_type,
side_effect?, return_type?, called_by?, called_by, file_pattern — rank-sorted output
calls?, file_pattern?, token_budget?)
codegraph_report(path) → god nodes, clusters, surprising connections
codegraph_affected(path, node, depth?) → BFS blast radius — what breaks if you change X?codegraph_query accepts question (natural language), node (exact/partial name), or both. codegraph_filter answers property questions ("which functions have side effects?", "all exported async handlers") without reading any files. Pass token_budget to any tool to get the highest-rank results within a token limit.
What's in each node (v1.2+):
Field | Example |
|
|
|
|
|
|
|
|
| first comment or JSDoc string |
| PageRank score — higher = more connected |
| parent class / interface names |
Step 3 — Visualize (auto-generated on every build):
codegraph_html(path, formats?) → regenerate visualizations on demandEvery codegraph_build automatically writes to <project>/codegraph-cache/:
graph.html — interactive vis.js force graph (dark theme, search, community toggle)
tree.html — D3 collapsible file hierarchy
callflow.html — Mermaid architecture diagrams per community
graph.graphml — Gephi / yEd export
obsidian/ — per-node .md vault with [[wikilinks]]
Available to HTTP-connected clients (Claude.ai, ChatGPT). Local AI clients use their native IDE tools.
read_file, write_file, patch_file, create_dir, list_dir, delete_file
git_status, git_diff, git_log, git_add, git_commit, git_push, git_pull, git_branch, git_stash, git_reset, git_show
Enable git tools with --access-git flag or access_git: true in config.
context-mcp [--data-dir <path>]
context-mcp-http [--port <number>] [--host <string>] [--access-git] [--data-dir <path>]Default port: 3100. Default data dir: ~/.context-mcp.
~/.context-mcp/contextconfig.json — auto-created on first run:
Field | Default | Description |
|
| OAuth client ID |
| auto-generated | OAuth signing secret |
|
| HTTP server port |
|
| HTTP bind host |
|
| Enable git tools for HTTP clients |
|
| Public URL for |
|
| OAuth redirect URI whitelist |
|
| Extra CORS origins |
Edit with ctx settings.
MIT
Scan a project directory and build the knowledge graph from code files. Uses tree-sitter AST (with regex fallback) for all code files. Fast, local, no API key needed. Run once per project; rebuild whenever code changes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to project root | |
| cluster | No | Run community detection after build (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the disclosure burden and does add useful context: local-only execution, no API key, tree-sitter AST with regex fallback. However, it does not disclose whether a rebuild overwrites the existing graph or how/where the graph is stored.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, purpose first, with each sentence contributing a distinct fact: what it does, how it parses code, and when to run it. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absent output schema and annotations, the description still covers the tool's purpose, input type, constraints, and usage lifecycle well. A note on overwrite semantics or the fact that sibling query tools should be used afterward would make it fully complete, but it is largely sufficient for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so path and cluster are already documented in the schema. The description only reinforces the meaning of the project directory and adds no extra detail about the cluster parameter or path formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('scan a project directory') and resource ('build the knowledge graph from code files'), making the tool's role immediately clear. Its build/update role is distinct from the query, report, and rendering siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage direction: run once per project and rebuild whenever code changes. It does not explicitly enumerate when to avoid this tool in favor of a sibling, but the lifecycle guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all nodes of a given type in the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| type | Yes | ||
| limit | No | Max results (default 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'list all nodes', implying a read-only operation, but does not explicitly confirm safety, nor does it disclose any behavioral traits like rate limits or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action. It is efficient but misses the opportunity to add value within the same sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain the return format (e.g., list of node IDs, objects). It does not. Additionally, it does not mention required parameters (path and type) or any constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'limit' has a description). The description adds no meaning for 'path' or 'type', leaving their purpose unclear. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list all nodes), the resource (nodes in the graph), and the constraint (given type). It is specific and distinguishes from sibling tools like codegraph_build, codegraph_path, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing nodes by type, providing clear context but no explicit when-not conditions or alternatives. It does not differentiate when to use this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the shortest relationship path between two concepts in the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| from | Yes | ||
| to | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the basic function. It does not disclose algorithm choice, performance implications, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, but it is concise with no wasted words. However, it is too brief to be maximally effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, low schema coverage, and absent annotations, the description is insufficient. It does not explain return format or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no meaning to the three required parameters (path, from, to).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (find) and resource (shortest relationship path) and distinguishes from sibling tools like codegraph_query and codegraph_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not specify use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask a structural question about the codebase OR look up a specific node by name — or both in one call. Pass question for natural-language traversal: what calls X, what does module Y depend on. Pass node for fast single-node lookup: returns type, file, depends_on, used_by. Pass both to get node detail + surrounding graph context together. Returns structured text within token_budget. Use before reading any files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Project root | |
| question | No | Natural language question about the codebase | |
| node | No | Node name or partial name to look up (type, file, deps, callers) | |
| token_budget | No | Max tokens in response (default 2000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose output fields, combined-mode behavior, and token_budget constraints. However, it does not state whether a prior codegraph_build is required, whether the operation is strictly read-only, or what happens when neither question nor node is supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and information-dense, but 'or both in one call' is repeated in the later 'Pass both' sentence, creating slight redundancy. Overall, most sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main modes and node-lookup return shape, but without an output schema it leaves question-mode response structure vague. It also omits behavior for a path-only call and the relationship to codegraph_build, both of which matter for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all four parameters, and the description adds real meaning beyond it: concrete question examples, the node lookup return fields, and the composition of question+node modes. This exceeds the baseline expected for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's actions and resource: asking a structural question about the codebase or looking up a specific node by name, with support for combining both. However, it does not explicitly differentiate from sibling tools like codegraph_context or codegraph_nodes, although 'single-node lookup' hints at a distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete conditional guidance: use question for natural-language traversal, node for single-node lookup, both for combined context, and use the tool before reading files. It does not name alternative sibling tools or state explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return CODEGRAPH_REPORT.md — god nodes, clusters, surprising connections, suggested questions.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It indicates that the tool returns a report and names its contents, but it does not disclose whether the report is written to a file or returned as text, whether the tool triggers a build, or what side effects or dependencies exist. This is a significant gap for a tool with no annotation safety cues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise, front-loaded sentence with no filler. The dash-separated list of report contents is information-dense and readable, and every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, no annotations, and a vaguely defined required path parameter, the description is too thin to support confident invocation. Missing context includes what the path should point to, whether a build must already exist, whether the tool creates or overwrites a file, and what the returned value actually is. The contents list helps, but core operational details are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'path' parameter has zero schema description coverage, and the description does not explain what path refers to (e.g., project path, graph database path, or output path). The description adds no meaning beyond the generic schema field name, leaving an agent to guess the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and a specific resource ('CODEGRAPH_REPORT.md'), and it lists the report's contents (god nodes, clusters, surprising connections, suggested questions). It is clearly about producing a report, though it does not explicitly distinguish itself from related siblings like codegraph_html or codegraph_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus its siblings, nor are alternatives named. The phrasing implies it is used when a report is needed, but there is no context about prerequisites such as requiring a prior codegraph_build, or when a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.8codegraph_buildcodegraph_nodescodegraph_pathcodegraph_querycodegraph_reportScored across 5 tools
Each tool has a clearly distinct purpose: building the graph, listing nodes, finding paths, querying, and generating reports. No overlap in functionality.
All tools follow a consistent 'codegraph_<verb>' pattern (build, nodes, path, query, report), making it easy to predict tool names.
Five tools is an ideal count for a focused code knowledge graph server, covering all essential operations without bloat or deficiency.
The tool surface covers building, querying (by node, path, natural language), listing nodes, and generating a summary report. No obvious gaps for code exploration.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.