semantic-search-mcp 0.3.0

MCP server for semantic code search using local embeddings

Semantic Search MCP Server

An MCP server that provides semantic code search using local embeddings. Search your codebase with natural language queries like "authentication middleware" or "database connection pooling".

Features

• Hybrid search: Combines vector similarity (Jina code embeddings) with FTS5 keyword matching using Reciprocal Rank Fusion
• 165+ languages: Tree-sitter parsing for Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Ruby, PHP, and more
• Incremental indexing: File watcher automatically detects additions, modifications, and deletions
• Respects .gitignore: Honors your project's .gitignore files (including nested ones)
• Auto-initialization: Model loads and codebase indexes in the background on server startup
• Zero external APIs: All embeddings generated locally with FastEmbed

Installation

uv tool install semantic-search-mcp

Or with pip:

pip install semantic-search-mcp

Or run directly without installing:

uvx semantic-search-mcp

Quick Start

Add to Claude Code

Option A: Project-level config (recommended)

After installing with uv tool install or pip install, create .mcp.json in your project root:

{
  "mcpServers": {
    "semantic-search": {
      "command": "semantic-search-mcp"
    }
  }
}

Option B: CLI

claude mcp add semantic-search -- semantic-search-mcp

Option C: Without installing (ephemeral)

If you prefer not to install, use uvx to run in an ephemeral environment:

{
  "mcpServers": {
    "semantic-search": {
      "command": "uvx",
      "args": ["semantic-search-mcp"]
    }
  }
}

Use

The server auto-initializes on startup.

Available Tools

Tool	Description
search_code	Search codebase with natural language
get_status	Get server state, progress, and statistics
pause_watcher	Pause file watching (events discarded)
resume_watcher	Resume file watching
reindex	Start full reindex (runs in background)
cancel_indexing	Cancel running indexing job
clear_index	Wipe all indexed data
exclude_paths	Add paths to ignore (session-only)
include_paths	Remove paths from exclusion list

How It Works

Indexing

On startup, the server:

1. Scans your codebase for supported file types
2. Parses code into semantic chunks (functions, classes, methods) using Tree-sitter
3. Generates embeddings for each chunk using Jina's code embedding model
4. Stores everything in a local SQLite database with vector search support

File Watching

The server monitors your codebase for changes in real-time:

Event	Action
File created	Parsed, embedded, and added to index
File modified	Re-indexed if content hash changed
File deleted	Removed from index

Changes are debounced (default 1s) to batch rapid modifications.

What Gets Indexed

Included:

• Files with code extensions: .py, .js, .ts, .tsx, .jsx, .go, .rs, .java, .c, .cpp, .h, .rb, .php, .swift, .kt, .scala, and more

Excluded:

• Files matching .gitignore patterns (all .gitignore files in your project are respected)
• Common non-code directories: node_modules, __pycache__, .venv, build, dist, .git, vendor, etc.
• Binary files and non-code file types

Configuration

Environment variables:

Variable	Default	Description
SEMANTIC_SEARCH_DB_PATH	.semantic-search/index.db	Index database location
SEMANTIC_SEARCH_EMBEDDING_MODEL	jinaai/jina-embeddings-v2-base-code	Embedding model
SEMANTIC_SEARCH_MIN_SCORE	0.3	Minimum relevance threshold (0-1)
SEMANTIC_SEARCH_DEBOUNCE_MS	1000	File watcher debounce in milliseconds
SEMANTIC_SEARCH_BATCH_SIZE	50	Files per batch (reduce if running out of memory)
SEMANTIC_SEARCH_MAX_FILE_SIZE_KB	512	Skip files larger than this (KB)
SEMANTIC_SEARCH_EMBEDDING_BATCH_SIZE	8	Texts per embedding call (reduce if OOM)
SEMANTIC_SEARCH_EMBEDDING_THREADS	4	ONNX runtime threads (higher = faster on multi-core)
SEMANTIC_SEARCH_USE_QUANTIZED	true	Use INT8 quantized model (30-40% faster)

Performance

GPU Acceleration

GPU acceleration is auto-detected and used when available:

Platform	Provider	Installation
NVIDIA	CUDA	pip install semantic-search-mcp[gpu]
Apple Silicon	CoreML	Automatic (M1/M2/M3)
AMD	ROCm	Install ROCm-enabled onnxruntime
Windows	DirectML	Install DirectML-enabled onnxruntime

Alternative Models

For faster indexing (with quality tradeoffs), you can use a lighter model:

Model	Dimensions	Speed	Best For
jinaai/jina-embeddings-v2-base-code	768	Baseline	Code search (default)
BAAI/bge-small-en-v1.5	384	~10x faster	General text
sentence-transformers/all-MiniLM-L6-v2	384	~32x faster	Speed priority

To use an alternative model:

export SEMANTIC_SEARCH_EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"

Note: Changing models requires a full reindex (delete .semantic-search/ directory).

UniXcoder (Experimental)

Microsoft UniXcoder is a code-specific model pre-trained on code + AST + comments. It may provide better semantic understanding of code structure, but is substantially slower (~20x slower than Jina).

Model	Dimensions	Speed	Languages
microsoft/unixcoder-base	768	~20x slower	6 (java, ruby, python, php, js, go)
microsoft/unixcoder-base-nine	768	~20x slower	9 (+ c, c++, c#)

Installation (requires additional dependencies):

pip install semantic-search-mcp[unixcoder]

Usage:

export SEMANTIC_SEARCH_EMBEDDING_MODEL="microsoft/unixcoder-base-nine"

When to use UniXcoder:

• You prioritize search quality over indexing speed
• Your codebase is small to medium sized
• You have GPU acceleration (CUDA or Apple Silicon MPS)

When to avoid UniXcoder:

• Large codebases (10,000+ files) - indexing will take hours
• You need fast initial indexing
• Running on CPU without GPU acceleration

Claude Code Integration

Skills and commands are automatically installed when the MCP server first starts:

• Skills → ~/.claude/skills/ (AI auto-discovery)
• Commands → ~/.claude/commands/ (user-invocable slash commands)

To manually reinstall or update:

semantic-search-mcp-install-skills

Available Slash Commands

Command	Description
/semantic-search-search <query>	Search codebase with natural language
/semantic-search-status	Check server status and index stats
/semantic-search-reindex	Trigger full codebase reindex
/semantic-search-cancel	Cancel running indexing job
/semantic-search-clear	Wipe all indexed data
/semantic-search-pause	Pause file watcher
/semantic-search-resume	Resume file watcher

Requirements

• Python 3.11+
• ~700MB disk for embedding model (downloaded on first run, ~150MB with INT8 quantization)
• ~1GB RAM for embedding model

License

MIT