claude-context-local

Your entire codebase as context. A local MCP server that gives Claude Code deep semantic understanding of your codebase — without sending a single byte to the cloud.

claude-context-local uses AST-aware chunking and hybrid semantic+keyword search to find all relevant code from your entire codebase. No multi-round file discovery needed. It brings results straight into Claude's context.

Cost-effective for large codebases: Instead of loading entire directories into Claude for every request (which can be very expensive), claude-context-local efficiently stores your codebase in a local vector database and only retrieves the code that's actually relevant — keeping your token usage manageable.

A lightweight alternative to zilliztech/claude-context that uses local embeddings instead of OpenAI + Zilliz Cloud.

Features

• 100% local — no API keys, no cloud, no data leaves your machine

• AST-aware chunking — splits code at function/class boundaries using tree-sitter (9+ languages), not arbitrary line counts

• Hybrid search — BM25 keyword + semantic embedding for best-of-both-worlds results

• Language-aware metadata — search results include language, symbol name, and symbol type

• Symbol dependency graph — "who calls this function?" / "what does this function call?"

• Auto-reindex — file watcher detects changes and re-indexes in the background

• Multi-project search — search across all your indexed projects at once

• Context-aware results — see surrounding code lines for better understanding

• Diff-aware search — search only code that changed since a git ref

• Lightweight — ONNX embeddings (~200 MB RAM, no PyTorch required)

• .gitignore-aware — respects your project's gitignore patterns

• Per-project isolation — each project gets its own index

• Incremental indexing — only re-indexes changed files (MD5 hash)

• 40+ file types supported out of the box

Related MCP server: Semantic Search MCP Server

Quick start

claude mcp add claude-context-local -- uvx claude-context-local

That's it. Restart Claude Code and the tools are available.

Alternative: pip

pip install claude-context-local
claude mcp add claude-context-local -- claude-context-local

Alternative: from source

git clone https://github.com/tazhate/claude-context-local.git
cd claude-context-local
pip install -e .
claude mcp add claude-context-local -- claude-context-local

MCP Tools

Usage examples

Once connected, Claude Code will automatically use these tools. You can also ask directly:

• "Index this project" — triggers index_project

• "Search for authentication logic" — semantic search across your codebase

• "Find all Python functions related to caching" — search_code with file_filter="*.py" and symbol_type="function"

• "Who calls the validate_email function?" — triggers find_symbol

• "What changed since yesterday?" — triggers search_diff

• "Search for error handling across all my projects" — triggers search_all

How it works

                           ┌───────────────┐
                           │  tree-sitter  │
                           │  AST parser   │
                           └───────┬───────┘
                                   │
┌─────────────┐     ┌──────────────┴───────┐     ┌──────────┐
│ Claude Code  │────>│ claude-context-local │────>│ ChromaDB │
│  (MCP client)│<────│    (MCP server)      │<────│ (vectors)│
└─────────────┘     └──────────────┬───────┘     └──────────┘
                         │    │    │
                    ┌────┴┐ ┌┴───┐ ┌┴────────┐
                    │ ONNX│ │BM25│ │ Symbol  │
                    │embed│ │keys│ │  Graph  │
                    └─────┘ └────┘ └─────────┘

1. Index: Walk project files → parse AST with tree-sitter → split at function/class boundaries → embed with ONNX model + build BM25 index + build symbol call graph → store in ChromaDB

2. Search: Hybrid — cosine similarity (semantic) + BM25 (keyword) merged with configurable alpha → ranked results with file paths, line numbers, language, symbol info

3. Incremental: MD5 hash per file — only changed files are re-processed

4. Watch: watchfiles monitors your project directory and triggers incremental re-index on save

AST-aware chunking

Traditional tools split files at arbitrary line boundaries, cutting functions in half. claude-context-local uses tree-sitter to parse code into AST and split at natural boundaries:

Files without tree-sitter support fall back to overlapping line-based chunking.

Per-project isolation

Each project gets its own ChromaDB database under ~/.cache/claude-context-local/<hash>/, where <hash> is derived from the absolute project path. Projects never mix.

Configuration

Environment variables (pass via claude mcp add -e KEY=VALUE):

Custom model example

# Use a code-specific model (requires: pip install claude-context-local[gpu])
claude mcp add claude-context-local \
  -e CCL_MODEL=jinaai/jina-embeddings-v2-base-code \
  -- uvx claude-context-local

# More keyword-heavy search
claude mcp add claude-context-local \
  -e CCL_HYBRID_ALPHA=0.4 \
  -- uvx claude-context-local

Resource usage

Supported file types

Code: .py .go .js .ts .tsx .jsx .rs .java .kt .c .cpp .h .hpp .cs .rb .php .swift .scala .sh .bash .lua .zig .nim .ex .exs .erl .nix

Config: .yaml .yml .toml .json .hcl .tf .sql .graphql .proto

Docs: .md .txt .rst

Web: .html .css .scss .less

Other: Dockerfile, Makefile

Comparison with zilliztech/claude-context

Security

• All data stays local — no network calls, no telemetry, no cloud

• Index files stored under ~/.cache/ with user-only permissions

• No secrets or credentials are ever indexed (lock files, .env excluded)

• CI runs pip-audit and bandit on every push

Development

git clone https://github.com/tazhate/claude-context-local.git
cd claude-context-local
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v

License

MIT