Context Mcp Server

Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.

One shared context store across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.

---

The Problem

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.

---

What It Solves

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

---

Installation

npm install -g context-mcp-server

Requires 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.uv

---

Quick Start

Run from your project root:

ctx install --initial

This installs Node.js + Python (ContextGraph) dependencies. Run once after installing the npm package.

Then write MCP config + AI instruction files:

ctx install --all

To install for a specific platform only:

ctx install --claude      # Claude Code
ctx install --cursor      # Cursor
ctx install --vscode      # VS Code Copilot
ctx install --gemini      # Gemini CLI
ctx install --codex       # Codex CLI
ctx install --windsurf    # Windsurf

For 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 port

---

CLI Reference

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 platforms

---

Security

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

---

Features

Memory

• context.resume — loads recent entries, active plans, and graph status; registers rootPath for sandboxing
• context.save — store context with 4 types: decision, bug, note, config
• 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

ContextGraph

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
signature	function fetchUser(id: string): Promise<User>
return_type	Promise<User>
side_effect	true (db write, HTTP call, fs op detected)
exported	true
docstring	first comment or JSDoc string
rank	PageRank score — higher = more connected
inherits / implements	parent class / interface names

Step 3 — Visualize (auto-generated on every build):

codegraph_html(path, formats?)            → regenerate visualizations on demand

Every 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]]

File & Git Tools

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.

---

Server Flags

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.

---

Config Reference

~/.context-mcp/contextconfig.json — auto-created on first run:

Field	Default	Description
client_id	"context-mcp"	OAuth client ID
client_secret	auto-generated	OAuth signing secret
port	3100	HTTP server port
host	"localhost"	HTTP bind host
access_git	false	Enable git tools for HTTP clients
public_url	null	Public URL for ctx online output
allowed_redirect_uris	["https://claude.ai"]	OAuth redirect URI whitelist
allowed_origins	[]	Extra CORS origins

Edit with ctx settings.

---

License

MIT