Nexus-MCP

Nexus-MCP

[PyPI version] [PyPI downloads] [PyPI downloads (pypistats)] [Python 3.10–3.12] [License: MIT] [CI] [Glama MCP server]

Hybrid search + code graph + semantic memory in a single local MCP server. About 90 MB idle and 460 MB with the embedding model loaded (measurements).

Nexus-MCP is a local code-intelligence MCP server for Claude Code, Codex, Cursor and any Model Context Protocol client. It gives AI agents precise, token-efficient answers about your codebase without cloud dependencies: no API keys, no data egress, no subscriptions.

Not sure yet? Measure it on your own code first. It is free, runs offline, calls no LLM and takes a few minutes:

uvx nexus-mcp-ci eval            # the current folderuvx nexus-mcp-ci eval --example  # or the Nexus-MCP source, if you have no project at hand

You get a verdict ("Strong fit", "Likely fit" or "Weak fit") and the tokens an agent needs to reach the right file, with and without Nexus-MCP. Nothing leaves your machine. See Evaluate on your project.

Ready?

pip install nexus-mcp-ciclaude mcp add nexus-mcp -- nexus-mcp-ci

Results at a glance

Live runs: Claude Code, Claude Sonnet, headless (claude -p), 12 questions per project, 3 runs each, version 2.1.0 (2026-10-28). The same code can vary by about 20% in cost with 3 runs per question (measured 2026-10-28). Search hit@1 on the four retrieval suites: jobscout 0.81, nexus_mcp 0.80, shop_repo 0.50, flask 0.64.

nexus-mcp-ci eval (the free offline check, no LLM) on 3 projects:

Nexus-MCP and GitNexus on Chromium base/ (C++, 4,243 files): 8 tasks, 3 runs each, 2026-11-04.

Nexus-MCP used fewer tokens than GitNexus on 8 of 8 tasks and cost less on 6; GitNexus cost $0.002 less on one task, and one task was a tie. Grep and Read cost less than both on this C++ code. Nexus-MCP cost less than Grep and Read on 3 of 8 tasks (the two needle tasks and WeakPtr). Each condition had the same agent, model, prompt and built-in tools, and each tool had its MCP server and its always-loaded instructions (method).

All numbers: benchmarks page · JSON · CSV.

The Problem It Solves

An agent that explores a codebase with Grep and Read pays for every call: each call is one more turn, and each turn reads the whole conversation again. Nexus-MCP answers a question about code in fewer calls. search returns the whole code of its top results, find_symbol returns the code of several names in one call, and graph returns every text reference beside the call edges.

The north star of the project is lower token use with the same accuracy. It is measured, not estimated: see Token efficiency and benchmarks/.

Evaluate on your project

Decide with your own numbers. The quick check is free, offline and calls no LLM:

uvx nexus-mcp-ci eval                                   # the current folderuvx nexus-mcp-ci eval path/to/project                   # another folderuvx nexus-mcp-ci eval https://github.com/pallets/flask  # a public repo (shallow clone)uvx nexus-mcp-ci eval --example                         # the Nexus-MCP source, offline

It asks about 30 questions made from your own code and compares Grep and Read with one Nexus-MCP search. The right answer is the file that defines the symbol, from the parser, never from the Nexus-MCP ranking. On this repo's source (59 files) it gave "Likely fit": 1,234 median tokens to reach the right file against 5,385, and the right file first in 93% of questions against 70%. On Chromium's base/ (3,638 files of C++, Java and Python) it gave "Strong fit": 950 median tokens against 17,998 (95% fewer), and the right file first in 70% of questions against 40%. On pallets/click (91 files, from its URL) it gave "Strong fit": 1,301 median tokens against 24,774 (95% fewer), and the right file first in 97% of questions against 27%. On a tiny project Grep and Read win, and the report says so.

Want the real agent cost? The agent tier runs your own Claude Code or Codex login on tasks from your code, with and without Nexus-MCP. It shows the cost first and asks:

nexus-mcp-ci eval --agent claude                       # Claude Sonnetnexus-mcp-ci eval --preset efficient --agent claude:haiku,claude:sonnet

Results are saved in ~/.nexus-mcp/evals/ (eval list, eval show <id>). eval share <id> posts the numbers (no code, no paths) to the community table, only after you say yes. Full guide: docs/EVALUATE.md. In Claude Code, the plugin adds /nexus-mcp:evaluate.

Privacy and Data

Your code stays on your machine. The server makes no network calls and has no telemetry.

• In: the package from PyPI, and the embedding model from Hugging Face once (set NEXUS_OFFLINE=1 after that). eval <url> also runs a git clone.
• Out: nothing, unless you run eval --agent (prompts and code go to Anthropic or OpenAI through your own CLI) or eval share (numbers only). Both ask first.
• Stored: the index, memories and graph in <project>/.nexus/ (it holds code: add it to .gitignore), the model in ~/.cache/huggingface/, eval results in ~/.nexus-mcp/evals/.

nexus-mcp-ci data where              # every location and its sizenexus-mcp-ci data clear --all        # dry run; add --yes to delete

Every location, the shell commands that do the same, and the uninstall steps: docs/PRIVACY.md.

Quickstart (60 seconds)

You need uv. Nothing else.

Ask your agent. Open your agent (Claude Code, Codex, Cursor, Gemini CLI) in your project and say:

Install Nexus-MCP from https://github.com/jaggernaut007/Nexus-MCP

The agent reads llms-install.md and runs one command. You can run the same command yourself:

uvx nexus-mcp-ci setup

setup finds the MCP clients on your machine, shows each change, and asks before it writes anything. It adds the server and a short skill that tells the agent when to use each tool. Add --dry-run to see the changes only, --client codex to pick one client, and --uninstall to remove what it wrote. Then reload your client (or start a new session) and ask something like "where do we retry failed payments?". The agent calls search, and index once, the first time in a project.

The server sends its own usage instructions when it connects, so the agent knows which tool answers which question even without the skill.

Other ways in, each with the same server:

• VS Code: Install in VS Code
• Cursor: the "Add to Cursor" button on the website
• Claude Desktop: download nexus-mcp.mcpb from the latest release and open it
• Gemini CLI: gemini extensions install https://github.com/jaggernaut007/Nexus-MCP
• Docker: docker run -i --rm -v "$PWD:/workspace" -v nexus-data:/data ghcr.io/jaggernaut007/nexus-mcp
• GitHub Actions: uses: jaggernaut007/Nexus-MCP@v2

All channels, and what each needs: docs/DISTRIBUTION.md.

Claude Code plugin

The plugin registers the server and the same routing skill. It runs the server through uvx, so it needs only uv, no pip install:

/plugin marketplace add jaggernaut007/Nexus-MCP/plugin install nexus-mcp@nexus-mcp

Use setup or the plugin for Claude Code, not both, or the server is registered twice. Tool names differ by route: mcp__nexus-mcp__search after setup, mcp__plugin_nexus-mcp_nexus-mcp__search through the plugin. The rest of this README writes bare names (search) and you do not need the prefix in prompts.

Optional: project instructions

If you want the rules in your own project file, a short block is enough:

## Code Navigation
The nexus-mcp server is connected. For questions about how this codebase works:- No setup call is needed; run `index` only if a tool says the project is not indexed.- Use `search` to find code, `find_symbol` for symbols, `map` for structure.- Use `graph` with `transitive=true` before you change a shared function. The call graph  is static, so also use `search` for dynamic call sites.- Use plain grep or read when you already know the file or the exact string.

The full routing guide is in docs/AGENT_ROUTING.md.

How It Works

Indexing Pipeline (8 steps)

Source files    │    ├─ Step 1: Discover ──────── walk tree, filter by ext/size/.gitignore    │    ├─ Step 2: Parse symbols ─── tree-sitter (parallel ThreadPool)    │           extracts: functions, classes, methods    │           captures: name, signature, docstring, line_start/end, language    │    ├─ Step 3: Parse graph ────── ast-grep (sequential for consistency)    │           extracts: containment edges, import edges, callee names of each function    │                     (indexing/call_resolver.py makes CALLS edges after the last batch;    │                      no inheritance edges yet)    │           output: UniversalGraph — nodes: modules, functions, classes;    │                                    edges: CONTAINS, IMPORTS, CALLS    │    ├─ Step 4: Transfer graph ── populate rustworkx PyDiGraph    │           O(1) node lookup by name, Rust-backed traversal    │    ├─ Step 5: Chunk ──────────── Symbol → CodeChunk    │           deterministic IDs: SHA256(file_path + symbol_name + line)    │           avoids duplicate inserts on incremental reindex    │    ├─ Step 6: Embed ──────────── bge-small-en: 384-dim    │           lazy-loaded, unloaded after indexing (try/finally)    │           GPU/MPS auto-detected; falls back to CPU    │    ├─ Step 7: Store ──────────── write to LanceDB `chunks` table (12-col PyArrow schema)    │           rebuild native FTS (Tantivy) index after write    │    └─ Step 8: Cleanup ────────── unload model, persist metadata (mtimes for incremental)                                  save rustworkx graph to SQLite (warm-start recovery)

Incremental reindex: mtime-based — only changed files are re-processed. Corrupt index detection triggers automatic full rebuild.

Search Pipeline

search("how does auth work")         │         ├─► vector_engine.search(query, n=30)  ← cosine similarity on 384-dim (bge-small-en) embeddings         │                                         "auth" finds "verify_credentials", "token_check"         │         ├─► bm25_engine.search(query, n=30)    ← Tantivy FTS on same LanceDB table         │                                         fast exact-keyword matching         │         ├─► graph_engine.boost(query, n=30)    ← structural relevance score         │                                         hub symbols (high in/out degree) boosted         │         └─► fusion.merge(v_results, b_results)                  │                  │  Reciprocal Rank Fusion: score = Σ weight_i / (k + rank_i)                  │  default weights: vector=0.5, bm25=0.3                  │                  └─► token_budget.truncate()   ← summary / detailed / full                           │                           └─► Top-N chunks, scored, formatted

Technology Stack

Token Efficiency

Two live runs, 12 questions each, with Claude Sonnet, 3 runs for each question and condition (72 runs each) and the prompt cache warm for both conditions. The result depends on the project.

Latest (commit a67e5b4, find_symbol shows an outline of a long class): the numbers are in Results at a glance, generated from benchmarks/published/results.json.

Only the nexus condition ran again for this commit; the Grep and Read numbers are the stored runs below. On django nexus is cheaper in total but still dearer on 8 of 12 questions (the short lookups). The one wrong answer on the private project came from a run that did not call find_symbol. With 3 runs for each question the same code can vary by about 20% in cost (measured 2026-10-28), so the change against the runs before the outline is inside the noise; all three recent nexus runs on the private project cost less than Grep and Read ($0.446 to $0.531 against $0.571), and on django nexus is about equal ($0.863 to $0.973 against $0.894). Details: docs/EVALS.md. The sections below are the runs before the outline.

Private 460-file Python project (2026-10-08, commit 91a338e):

Nexus is cheaper on 7 questions, equal on 3 and dearer on 2 (the two impact questions, by $0.005 and $0.004). The saving comes from fewer turns and from smaller tool results than the whole-file reads of Grep and Read (see the cost split below). Per question numbers are in docs/EVALS.md. The same questions on 2026-10-07 (before exact names, code in find_symbol, the smaller tool list and the warm-up call) gave nexus 6% more cost than Grep and Read.

Django, a public repository (3,000 files; 2026-10-27, commit 3fa8810):

On django nexus uses fewer turns but costs more. It is cheaper on the questions where Grep and Read need 18 to 24 turns (SQLCompiler.as_sql -21%, URLResolver.resolve -10%) and dearer on short lookups that take 2 or 3 turns. Django is a repository that the model knows from training, so part of this measures the model. One ground truth was corrected after the run (a question asked for a value, and the scorer also required a file name); details in docs/EVALS.md.

Why: the cost split of the traces. The parts below add up to the reported cost of each run.

• The 3,600 extra prompt tokens on each turn cost little: a cache read is $0.20 per million.
• Tool results are written to the cache at $4 per million, 20 times the read price. So the size of a result matters more than the size of the prompt.
• On jobscout the agent does not know the code and reads whole files (10,000 characters for each Read). A find_symbol result of 9,700 characters replaces a Read and saves a turn.
• On django the agent knows the code and reads short line ranges (3,400 characters for each Read). A find_symbol result of 9,200 characters is larger than the read that it replaces. A class lookup sends up to 6,000 characters of the class body: CharField cost $0.023 with nexus and $0.013 with Grep.

This led to the outline for a class in find_symbol (methods and lines, not the body). With it, nexus on django went from $0.973 to $0.863 (see "Latest" above). Details and the other candidates are in docs/EVALS.md.

The saving is large on a project that the model does not know and small on one that it knows. Run benchmarks/ on your own project before you rely on it.

The 8 Tools

New in v2.3.0 (no breaking change): uvx nexus-mcp-ci setup installs the server and the skill into your MCP clients, new install routes cover Claude Desktop, Gemini CLI, VS Code, Cursor, Docker and GitHub Actions, and the license is now MIT. The MCP tools do not change.

New in v2.2.0 (no breaking change): nexus-mcp-ci eval measures Nexus-MCP on your own code (Evaluate), and nexus-mcp-ci data shows and clears every stored file (Privacy). The MCP tools do not change.

v2.1.0 breaking change: explain and health are removed from the MCP tool list, and several rarely used parameters are removed from the schemas (see CHANGELOG). find_symbol now returns the code with callers and callees.

v2.0.0 breaking change: find_callers/find_callees/impact merged into graph, overview/architecture merged into map, and remember/recall/forget merged into memory — see CHANGELOG for the old→new mapping and ADR-017 for why. Fewer, richer tools route better under MCP Tool Search than many thin ones.

Discovery & Indexing

Search

Graph Analysis

Memory

Install

From PyPI (recommended)

pip install nexus-mcp-ci
# GPU (CUDA) support — adds ONNX CUDA execution providerpip install nexus-mcp-ci[gpu]

From Source

git clone https://github.com/jaggernaut007/Nexus-MCP.gitcd Nexus-MCP./setup.sh           # creates venv, installs, verifies# orpip install -e ".[dev]"

Python 3.10–3.12 supported. Python 3.13+ is not yet supported by the current dependency stack, and the packaged Glama/Docker build uses Python 3.12 for compatibility. Optional: rg (ripgrep) for 100% search coverage fallback on unindexed files.

The deprecated jina-code model requires ONNX Runtime. If you see ONNX/Optimum errors:

bash

pip install "sentence-transformers[onnx]" "optimum[onnxruntime]>=1.19.0"

The default bge-small-en model needs neither ONNX nor trust_remote_code.

MCP Client Setup

Claude Code

# Minimalclaude mcp add nexus-mcp -- nexus-mcp-ci
# GPU embeddingsclaude mcp add nexus-mcp -e NEXUS_EMBEDDING_DEVICE=cuda -- nexus-mcp-ci
# Virtualenv install — pass the full binary pathclaude mcp add nexus-mcp -- /path/to/.venv/bin/nexus-mcp-ci

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{  "mcpServers": {    "nexus-mcp": {      "command": "nexus-mcp-ci",      "args": [],      "env": {        "NEXUS_EMBEDDING_DEVICE": "cpu"      }    }  }}

Cursor / Windsurf / Cline / Any MCP Client

{  "nexus-mcp": {    "command": "nexus-mcp-ci",    "transport": "stdio"  }}

Agent Integration Patterns

CLAUDE.md boilerplate (drop into project root)

## Code Intelligence — nexus-mcp
1. **Session start**: no setup call. Run `index` only if a tool says "No codebase indexed"2. **To find code you cannot name**: `search`, before reading files one by one3. **To see symbols you can name**: `find_symbol`, with all the names in one call4. **Before refactoring**: `graph` with `transitive=true` to assess blast radius. The call graph is static (no dynamic dispatch), so also use `search` to find call sites.5. **For project orientation**: `map` with `detail="summary"` or `detail="architecture"`6. **When you know the exact file or string**: plain grep or read is fine

Typical agent tool-call sequence

# Session startstatus()               → "indexed: True, 8,412 chunks, 1,203 symbols, 87 MB"
# Code discoverysearch("JWT token validation", limit=10)  → auth/jwt.py:42  validate_token()         score=0.94  → auth/middleware.py:18  require_auth()    score=0.87  → tests/test_auth.py:91  test_valid_jwt()  score=0.81
# Symbols you can namefind_symbol("validate_token, require_auth")  → the code of each, file and lines  → callers: [post_order, ...], callees: [...]
# Pre-refactor safety checkgraph("validate_token", direction="callers", transitive=True)  → total_impacted: N          # a lower bound: dynamic calls are not visible
# Locate call sites with search insteadsearch("validate_token(", mode="bm25")  → auth/middleware.py:18  require_auth()  ...  → auth/login.py:57  login_required()     ...

Multi-folder monorepo indexing

# Index multiple roots in one call — processed sequentially, shared enginesindex(path="packages/api/src,packages/shared/src,packages/cli/src")
# Or use the paths parameter for additional rootsindex(path="packages/api/src", paths="packages/shared/src,packages/cli/src")

Configuration

All settings via NEXUS_ environment variables:

The Python package defaults to bge-small-en. The Dockerfile, docker/Dockerfile.stdio and glama.json use the same default. jina-code still loads, with a warning, so an existing index keeps working. It is deprecated and will be removed in a future major release.

Embedding Models

After changing model, re-index. Embeddings from different models are incompatible.

Comparison

vs. other code-intelligence MCP servers

Features only, from each project's own documentation. We make no performance claims about other tools: run nexus-mcp-ci eval on your code instead.

Other servers in this space include codebase-memory-mcp, code-graph-rag, code-index-mcp and ast-grep-mcp. Check each project's docs. Corrections to this table are welcome.

vs. Other MCP Servers

vs. AI Code Tools

Development

git clone https://github.com/jaggernaut007/Nexus-MCP.gitcd Nexus-MCPpip install -e ".[dev]"
pytest -v                    # all tests (-m "not slow" skips the performance ones)pytest -m "not slow"         # skip performance benchmarkspytest tests/test_hybrid_search.py  # single moduleruff check .                 # lint

Project Structure

src/nexus_mcp/├── server.py              # FastMCP entrypoint — 10 thin tool wrappers (permission guard, rate limit, audit), graceful shutdown├── core_api.py            # Transport-agnostic tool logic + input validation; importable without MCP├── config.py              # Settings (NEXUS_ env prefix)├── state.py               # Global singleton SessionState├── core/│   ├── models.py          # Symbol, ParsedFile, CodebaseIndex, Memory│   ├── graph_models.py    # UniversalNode, Relationship│   ├── interfaces.py      # IParser, IEngine protocols│   └── exceptions.py      # NexusException hierarchy├── parsing/│   ├── treesitter_parser.py   # Symbol extraction (parallel)│   ├── astgrep_parser.py      # Structural graph extraction (sequential)│   ├── language_registry.py   # 25+ language definitions│   └── file_watcher.py        # Debounced watchdog for live reindex├── engines/│   ├── vector_engine.py   # LanceDB cosine similarity search│   ├── bm25_engine.py     # LanceDB native FTS (Tantivy)│   ├── graph_engine.py    # rustworkx PyDiGraph with RLock│   ├── live_grep.py       # rg/grep fallback for unindexed or sparse results│   ├── fusion.py          # Reciprocal Rank Fusion├── indexing/│   ├── pipeline.py        # 8-step indexing pipeline│   ├── embedding_service.py   # ONNX Runtime, GPU/MPS auto-detect│   ├── parallel_indexer.py    # ThreadPool over files│   └── chunker.py         # Symbol → CodeChunk with deterministic IDs├── memory/│   └── memory_store.py    # LanceDB-backed memory, TTL, 6 types├── analysis/│   └── code_analyzer.py   # Cyclomatic/cognitive complexity, smells├── formatting/│   ├── token_budget.py    # Token counting and truncation│   └── response_builder.py  # Structured responses├── persistence/│   └── store.py           # SQLite graph persistence├── security/│   ├── permissions.py     # READ/MUTATE/WRITE tool categories│   └── rate_limiter.py    # Token-bucket, per-tool, thread-safe└── middleware/    └── audit.py           # Structured audit logs, correlation IDs, field redactionbenchmarks/                # Token-efficiency benchmark harness (ADR-018)self_test/                 # End-to-end demo of the 8 tools and the Python APIplugin/                    # Claude Code plugin: registers the server + routing skill

Adding a New Tool

1. Add the logic as a plain function in core_api.py
2. Validate input there with the validate_* helpers (validate_path, validate_symbol_name, validate_query)
3. Add a thin wrapper in server.py decorated with @mcp.tool() and @_audited, and call _guard("<tool>") first
4. Add the permission category to security/permissions.py
5. Write tests in tests/
6. Update self_test/demo_mcp.py to exercise the tool

Adding a New Language

1. Add entry to parsing/language_registry.py with the tree-sitter grammar
2. Add structural patterns to parsing/astgrep_parser.py for call/import extraction
3. Add test fixtures in tests/fixtures/

Self-Test

Verify your installation exercises the 8 tools and the Python API end-to-end:

python self_test/demo_mcp.py                   # built-in sample projectpython self_test/demo_mcp.py /path/to/project  # your own codebase

Expected output: the 8 tools and the Python API exercised with pass/fail per tool and a summary.

Known Limitations

• Sequential graph parsing: ast-grep runs sequentially (not parallel) to keep the call graph consistent. This is the main indexing bottleneck on large codebases.
• bge-small-en uses PyTorch: The default model runs on PyTorch, not ONNX.
• No incremental graph updates: Graph is rebuilt in full on incremental reindex (only vector/BM25 are incremental at the chunk level).
• No SSE transport: Only stdio transport is currently supported.
• Language coverage: 25+ languages get tree-sitter symbol extraction. ast-grep structure (functions, classes, imports) covers Python, JavaScript, TypeScript, Go, Java, and Rust; other languages have no graph structure.
• Call edges are static and name-based. graph() and the callers/callees fields of find_symbol() come from parsing, not runtime tracing. Edges exist for Python, JavaScript, TypeScript, Go, Java and Rust. A call resolves only when the callee is in the same file, in an imported file, or has a unique name in the index. A name shared by several definitions gets no edge, so results are a lower bound. Dynamic dispatch, monkey-patching, callbacks and reflection do not show up, so treat graph(transitive=True) as a lower bound on blast radius.
• Complexity is approximate: cyclomatic complexity counts branch points per function. Only Python counts and/or, and only Python functions get docstrings on graph nodes.
• Auto-reindex has a detection lag: with the file watcher enabled (default), edits are picked up after a short debounce, and status()/search() run a throttled staleness check as a backstop — not an instant, per-call guarantee of freshness.

Architecture Decision Records

Key decisions are documented in docs/adr/:

Documentation

Start at the docs index.

• Evaluate on your project — The free offline check, the agent tier, saving and sharing results
• Privacy and data — What goes in and out, where data is stored, how to remove it
• Benchmarks — Every published number, with JSON and CSV
• Installation Guide — Prerequisites, client-specific setup, troubleshooting
• Architecture — Data flow, component design, memory budget analysis
• Usage Guide — Full tool reference with examples
• Developer Guide — Contributing, adding tools/engines/languages
• Research Notes — Library evaluations and technology deep-dives

Acknowledgments

Nexus-MCP consolidates two earlier open-source projects:

• CodeGrok MCP by rdondeti (Ravitez Dondeti, MIT) — Contributed the symbol extraction pipeline, embedding service, parallel indexer, core data models, and memory retrieval system.
• code-graph-mcp by entrepeneur4lyf — Contributed the ast-grep structural parser, rustworkx graph engine, complexity analysis, and relationship extraction.

Source files retain "Ported from" attribution in their module docstrings. See ADR-001 for the consolidation rationale.

License

MIT. Free to use, copy, modify and distribute, for any purpose, including at work.

Versions 2.0.1 to 2.2.3 were released under the PolyForm Noncommercial License 1.0.0. Anyone who obtained one of those versions keeps the terms they got. Versions 0.1.0, 0.1.1 and 2.0.0 were MIT. Every new release is MIT.

If Nexus-MCP saves you tokens at work, a star or a sponsorship is welcome. Neither is required.