claude-context-local — Summary

A local semantic code search MCP server that indexes codebases with Google's EmbeddingGemma model (1.2–1.3 GB, runs 100% locally) and serves search results to Claude Code via 8 MCP tools. The core promise: semantic search without API costs or cloud data transmission — "your code never leaves your machine."

The system uses AST-based chunking for Python (rich metadata) and tree-sitter for 8 other languages (JS/TS/JSX/TSX/Svelte/Go/Java/Rust/C/C++/C#). Embeddings are stored in a FAISS index (CPU by default, GPU acceleration via CUDA or Apple Silicon MPS). A Merkle DAG tracks incremental changes so re-indexing only processes modified files.

Built by FarhanAliRaza (GitHub), described as "Beta Release" with 231 stars and installation via a one-liner curl command. Part of a workflow where the user tells Claude Code to "index this codebase" and then can ask questions like "find authentication code" to get semantically relevant results without burning tokens on full file context.

Compared to seeds: closest to ccmemory (Archetype 3 — MCP-anchored toolserver for memory/context) but ccmemory stores knowledge graph memories while claude-context-local stores code embeddings. Both use a local MCP server for persistence, but the underlying store is completely different (FAISS vector index vs. Neo4j graph).

claude-context-local — Overview

Origin

Created by FarhanAliRaza (GitHub), published late 2025. Beta release. The repo description: "Code search MCP for Claude Code. Make entire codebase the context for any coding agent. Embeddings are created and stored locally. No API cost."

Philosophy

"Claude's code context is powerful, but sending your code to the cloud costs tokens and raises privacy concerns. This project keeps semantic code search entirely on your machine."

Three core claims:

1. Privacy: Code never leaves the machine
2. Cost: No API keys, no token costs for embedding
3. Speed: Fewer tokens needed because Claude gets precise semantic matches instead of loading entire files

Supported Languages (15 file extensions)

Python, JavaScript, TypeScript, JSX, TSX, Svelte, Go, Java, Rust, C, C++, C#

Chunking Strategy

Two-tier:

• Python: AST-based chunking with rich metadata (function names, class hierarchies, docstrings)
• Other 8 languages: tree-sitter for syntax-aware chunking

Embedding Model

Google's EmbeddingGemma (~1.2–1.3 GB download). Runs locally via SentenceTransformer. Device selection: CUDA → MPS (Apple Silicon) → CPU.

Key Design Decision

The choice of EmbeddingGemma over a simpler embedding model means the first run requires a 1.2 GB model download. Subsequent runs use the cached model. This is a significant installation friction point for a "local-first" tool.

claude-context-local — Architecture

Distribution

mcp-server — Python package installed via curl one-liner.

Install

curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

# Or wget:
wget -qO- .../install.sh | bash

Register MCP Server

claude mcp add code-search --scope user -- \
  uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

What the Installer Does

1. Installs uv (Python package manager) if missing
2. Clones/updates repo to ~/.local/share/claude-context-local
3. Installs Python deps with uv sync
4. Downloads EmbeddingGemma model (~1.2–1.3 GB) if not cached
5. Optionally installs faiss-gpu if NVIDIA GPU detected

Source Directory Tree

claude-context-local/
├── chunking/
│   ├── multi_language_chunker.py   # Orchestrator (Python AST + tree-sitter)
│   ├── python_ast_chunker.py       # Python-specific (rich metadata)
│   └── tree_sitter.py              # JS/TS/Go/Java/Rust/C/C++/C#
├── embeddings/
│   └── embedder.py                 # EmbeddingGemma; device=auto; offline cache
├── search/
│   ├── indexer.py                  # FAISS index (CPU default; GPU when available)
│   ├── searcher.py                 # Ranking + filters
│   └── incremental_indexer.py      # Merkle-driven incremental indexing
├── merkle/
│   ├── merkle_dag.py               # Content-hash DAG of workspace
│   ├── change_detector.py          # Diffs snapshots to find changed files
│   └── snapshot_manager.py         # Snapshot persistence + stats
├── mcp_server/
│   ├── server.py                   # MCP entry point (stdio/HTTP)
│   ├── code_search_server.py       # Server logic
│   ├── code_search_mcp.py          # FastMCP tool registration
│   └── strings.yaml                # Tool descriptions (externalised)
└── scripts/
    ├── install.sh                  # One-liner installer
    ├── download_model_standalone.py
    └── index_codebase.py

Data Flow

User codebase (15 extensions)
  → Chunking (AST/tree-sitter)
  → EmbeddingGemma (local) → float vectors
  → FAISS index (~/.claude_code_search/)
  
Query ("find authentication code")
  → EmbeddingGemma → query vector
  → FAISS similarity search
  → Ranked code chunks
  → MCP response to Claude Code

Storage

Index stored at ~/.claude_code_search/ — preserved across updates.

Transport

stdio (default) or HTTP/SSE (via --transport flag).

claude-context-local — Components

MCP Tools (8, from strings.yaml)

Key Tool Signatures

# search_code
search_code("authentication")  # minimal
search_code("authentication", k=10, file_pattern="*.py")  # full

# index_directory
index_directory("/path/to/project")  # minimal
index_directory("/path/to/project", project_name="project", incremental=False)  # full

# find_similar_code
find_similar_code(chunk_id, k=5)  # chunk_id from search_code results

Skills (0)

None.

Hooks (0)

None.

Commands (0)

No slash commands.

Scripts (3)

MCP Resources (1)

The search://stats resource provides detailed index statistics.

MCP Prompts (1)

The search_help prompt provides usage guidance for code search tools.

claude-context-local — Uniqueness

differs_from_seeds

Closest seed is ccmemory (Archetype 3 — MCP-anchored toolserver). Both use a local MCP server for persistence, but ccmemory stores knowledge graph memories (Neo4j + vector) about conversation and code decisions, while claude-context-local stores code embeddings for semantic search. The key difference: ccmemory's memory is about what the agent decided; claude-context-local's memory is about what the code contains. Also closest to taskmaster-ai in the sense of being a local-first MCP server with file-based persistence, but taskmaster-ai manages tasks, not code embeddings.

Positioning

The only framework in this batch (and likely the corpus) that uses a local neural embedding model (EmbeddingGemma) for code search. All other memory/context frameworks use either file-based (keyword) storage, SQLite, or cloud-based vector services. This framework is the only one that brings embedding-based semantic search 100% locally.

Distinctive Opinion

"Claude's code context is powerful, but sending your code to the cloud costs tokens and raises privacy concerns."

The framework makes a strong privacy argument for local embeddings over cloud APIs. This resonates particularly for enterprise or security-conscious users.

Observable Failure Modes

1. 1.2 GB model download: First-run friction that blocks "quick start" users
2. FAISS index staleness: If incremental=False is needed but the user only calls with incremental=True, stale results
3. No real-time updates: Index must be explicitly re-run; auto-indexing on file save not implemented
4. GPU detection ambiguity: faiss-gpu install is attempted interactively — breaks in CI/headless environments
5. Beta quality: Self-described as "Core functionality working / benchmarks coming soon / please report issues"
6. No chunk deduplication: Duplicate code (copy-pasted functions) creates redundant search results

What Makes It Novel vs. the 11 Seeds

• Only framework using a local neural embedding model (EmbeddingGemma) for code search
• Only MCP server with AST-based Python chunking and tree-sitter for multi-language support
• Only framework with Merkle DAG-based incremental indexing
• Only framework explicitly positioning privacy (no cloud) as a primary value proposition
• Only framework supporting GPU acceleration (CUDA + MPS) for embedding generation