semantic-code-index-mcp

MCP server for Claude Code: semantic code search with SQLite + local embeddings (free, no API key needed).

Instead of reading your entire codebase, Claude searches semantically — finding relevant code by meaning, not just keywords. Saves 80-90% tokens per query.

Quick Install (npx)

cd /path/to/your/project
npx semantic-code-index-mcp install

This automatically:

• Creates .claude/mcp.json and .mcp.json (merged with existing config)
• Adds .claude/rules/semantic-search.md so Claude prefers semantic search
• Updates .gitignore

Requires Python 3.11+ and uv (brew install uv or pip install uv).

Uninstall

npx semantic-code-index-mcp uninstall

Cleanly removes all config. If you have other MCP servers configured, they are preserved.

Install from source (dev)

git clone https://github.com/thinhdo/semantic-code-index-mcp
cd semantic-code-index-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Install into a project using local binary
semantic-code-index-mcp install /path/to/your/project

# Or via npx with --local flag
npx semantic-code-index-mcp install /path/to/project --local .venv/bin/semantic-code-index-mcp

Usage

Once installed, open Claude Code in your project. First time, ask Claude:

Index this project

After that, Claude will automatically use semantic_search for code exploration. The index auto-syncs when files change — no manual steps needed.

Tools

How it works

1. Chunking — source files are split into overlapping chunks (~100 lines, 15-line overlap)
2. Embedding — each chunk is vectorized locally using fastembed (BAAI/bge-small-en-v1.5, ONNX)
3. Storage — vectors + metadata stored in SQLite (at ~/.cache/semantic-code-index/<hash>/)
4. Search — hybrid retrieval: cosine similarity + FTS5 BM25, fused with Reciprocal Rank Fusion
5. Auto-sync — on each search, changed files are detected and re-indexed automatically

Token savings

Each search returns only relevant snippets instead of the full repo. Example on a ~10k token repo:

On larger repos (100k+ tokens), savings are even more significant.

Environment variables

• SEMANTIC_CODE_ROOT or WORKSPACE_ROOT: root directory of the project to index (default: MCP server's working directory)

Notes

• Token counting uses tiktoken encoding cl100k_base (approximate for Claude/GPT-4), not actual billing
• First run downloads the ONNX embedding model (~30MB)
• Vector search scans all chunks in SQLite; very large repos may need scaling (sqlite-vec / ANN)