Nexus-MCP

Nexus-MCP

The only MCP server with hybrid search + code graph + semantic memory — fully local.

Nexus-MCP is a unified, local-first code intelligence server built for the Model Context Protocol. It combines vector search, BM25 keyword search, and structural graph analysis into a single process — giving AI agents precise, token-efficient code understanding without cloud dependencies.

Why Nexus-MCP?

AI coding agents waste tokens. A lot of them. Every time an agent reads full files to find a function, grep-searches for keywords that miss semantic intent, or makes multiple tool calls across disconnected servers — tokens burn. Nexus-MCP fixes this.

Token Efficiency: The Numbers

Estimated savings per coding session: 15,000–40,000 tokens (30–60% reduction) compared to standalone agentic file browsing.

Three Verbosity Levels

Every tool respects a token budget — agents request only the detail they need:

vs. Standalone Agentic Development (No Code MCP)

Without a code intelligence server, AI agents must:

• Read entire files to find one function (~500–2,000 tokens/file, often 5–10 files per query)
• Grep for keywords that miss semantic intent ("auth" won't find "verify_credentials")
• Manually trace call chains by reading file after file
• Lose all context between sessions — no persistent memory

Nexus-MCP replaces this with targeted retrieval: semantic search returns the exact chunks needed, graph queries trace relationships instantly, and memory persists across sessions.

vs. Competitor MCP Servers

vs. AI Code Tools (Cursor, Copilot, Cody, etc.)

Nexus-MCP's unique combination: No other tool delivers hybrid search + code graph + semantic memory + token budgeting + full privacy in a single MCP server.

Key Features

• Hybrid search — Vector (semantic) + BM25 (keyword) + graph (structural) fused via Reciprocal Rank Fusion, then re-ranked with FlashRank
• Code graph — Structural analysis via rustworkx: callers, callees, imports, inheritance, change impact
• Dual parsing — tree-sitter (symbol extraction) + ast-grep (structural relationships), 25+ languages
• Semantic memory — Persistent knowledge store with TTL expiration, 6 memory types, semantic recall
• Explain & Impact — "What does this do?" and "What breaks if I change it?" in single tool calls
• Token-budgeted responses — Three verbosity levels (summary/detailed/full) keep context windows lean
• Multi-folder indexing — Index multiple directories in one call, processed folder-by-folder with shared engines
• Incremental indexing — Only re-processes changed files; file watcher support
• Multi-model embeddings — 2 models (jina-code default, bge-small-en), GPU/MPS auto-detection
• Low memory — <350MB RAM target (ONNX Runtime ~50MB, mmap vectors, lazy model loading)
• Fully local — Zero cloud dependencies, no API keys, all processing on your machine
• 15 tools, one server — Consolidates what previously required 2 MCP servers (17 tools) into one

Prerequisites

• Python 3.10+ (tested on 3.10, 3.11, 3.12)
• pip (comes with Python)

Install

Option 1: pip install from PyPI (recommended)

pip install nexus-mcp-ci

With optional extras:

# With GPU (CUDA) support
pip install nexus-mcp-ci[gpu]

# With FlashRank reranker for better search quality
pip install nexus-mcp-ci[reranker]

# Both
pip install nexus-mcp-ci[gpu,reranker]

Option 2: From source (for development)

git clone https://github.com/jaggernaut007/Nexus-MCP.git
cd Nexus-MCP

# Setup script (creates venv, installs, verifies)
./setup.sh

# Or manual install with dev deps
pip install -e ".[dev]"

Note: The default embedding model (jina-code) requires ONNX Runtime. This is included automatically. If you see errors about missing ONNX/Optimum, run:

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

To use a lighter model that doesn't need trust_remote_code, set NEXUS_EMBEDDING_MODEL=bge-small-en.

See the full Installation Guide for all options, MCP client integration, and troubleshooting.

Run

nexus-mcp

The server starts on stdio (the default MCP transport). Point your MCP client at the nexus-mcp command.

Add to Your MCP Client

Claude Code

# Basic setup
claude mcp add nexus-mcp-ci -- nexus-mcp-ci

# With a specific embedding model
claude mcp add nexus-mcp-ci -e NEXUS_EMBEDDING_MODEL=bge-small-en -- nexus-mcp-ci

Tip: If you installed in a virtual environment, use the full path so the MCP client finds the right Python:

claude mcp add nexus-mcp-ci -- /path/to/Nexus-MCP/.venv/bin/nexus-mcp-ci

Claude Desktop

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Cursor / Windsurf / Cline / Other MCP Clients

Add to your MCP client's server config:

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

See the full Installation Guide for client-specific instructions.

MCP Tools (15)

Core

Graph Analysis

Memory

Configuration

All settings can be overridden via NEXUS_ environment variables:

Self-Test Demo

Verify your installation by running the end-to-end demo that exercises all 15 tools:

python self_test/demo_mcp.py                  # Uses built-in sample project
python self_test/demo_mcp.py /path/to/project  # Or test against your own codebase

See self_test/README.md for details.

Development

pip install -e ".[dev]"     # Install with dev deps
pytest -v                   # Run tests (441 tests)
pytest -m "not slow"        # Skip performance benchmarks
ruff check .                # Lint
nexus-mcp-ci                # Run server

How It Works

search("how does auth work")
  |
  |-- vector_engine.search(query, n=30)    -- semantic similarity (embeddings)
  |-- bm25_engine.search(query, n=30)      -- keyword matching (exact terms)
  |-- graph_engine.boost(query, n=30)      -- structural relevance (callers/callees)
  |                                            |
  |              Reciprocal Rank Fusion (weights: 0.5 / 0.3 / 0.2)
  |                                            |
  |                        FlashRank re-ranking (top 20)
  |                                            |
  |                      Token budget truncation (summary/detailed/full)
  |                                            |
  v
  Top-N results, formatted to verbosity level

Architecture

Documentation

• Installation Guide — Prerequisites, install steps, MCP client integration, troubleshooting
• Architecture — System design, data flow, components, memory budget
• Usage Guide — Tool reference, configuration, best practices
• Developer Guide — Setup, testing, contributing, adding tools/engines
• ADRs — 11 Architecture Decision Records
• Research Notes — Deep dives on libraries and technology choices

Acknowledgments

Nexus-MCP consolidates and extends two earlier projects:

• CodeGrok MCP by rdondeti (Ravitez Dondeti) — Semantic code search with tree-sitter parsing, embedding service, parallel indexing, and memory retrieval. Core models, symbol extraction, and the embedding pipeline were ported from CodeGrok. Originally licensed under MIT.
• code-graph-mcp by entrepeneur4lyf — Code graph analysis with ast-grep structural parsing, rustworkx graph engine, and complexity analysis. Graph models, relationship extraction, and code analysis were ported from code-graph-mcp.

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

License

MIT — see LICENSE for details.