semantic-code-index-mcp 0.3.0

MCP server: semantic code search with SQLite + local free embeddings

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

Tool	Description
index_project	Full re-index of the codebase
sync_index	Incremental sync (new/changed/deleted files only)
semantic_search	Hybrid search: semantic vectors + keyword BM25. Auto-syncs before searching
list_indexed_files	List all indexed files with token count and chunk count
get_file_chunks	Get full content of a file's indexed chunks
token_usage_stats	Compare: tokens if reading full repo vs tokens used by searches
search_log	View recent search history with token usage and savings

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:

Query	Result tokens	Full repo	Saved
"how does embedding work"	1,569	9,577	83%
"install setup"	925	9,577	90%
"chunking strategy"	1,331	9,577	86%

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)