semantic-search-mcp

Semantic code search MCP server for AI coding agents. Local embeddings, no API keys.

AI coding agents (opencode, Claude, Cursor) can grep for exact words — but semantic-search-mcp lets them find code by meaning. Ask "where do we handle authentication?" and get back config/auth.php, AuthController.php, login.blade.php — even if the word "handle" doesn't appear.

Powered by: all-MiniLM-L6-v2 via ONNX runtime. Everything runs locally, no data leaves your machine.

Quick Start

1. Install

npm install -g semantic-search-mcp

Or run without installing:

npx semantic-search-mcp

2. Connect to your AI agent

opencode — add to opencode.jsonc:

{
  "mcp": {
    "semantic-search": {
      "type": "local",
      "command": ["npx", "-y", "semantic-search-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

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

3. Done!

Restart your AI agent. The first search will index your codebase (~5-15 min depending on size). Subsequent searches are instant (cached).

Related MCP server: CodeGrok MCP

Configuration

Create .semantic-search.json in your project root:

{
  "extensions": [".php", ".js", ".jsx", ".ts", ".tsx"],
  "skipDirs": ["node_modules", "vendor", ".git", "dist"],
  "model": "Xenova/all-MiniLM-L6-v2",
  "chunkThreshold": 300,
  "maxChunksPerFile": 4
}

Or use environment variables:

export SEMANTIC_SEARCH_EXTENSIONS=".php,.js,.jsx,.ts,.tsx"
export SEMANTIC_SEARCH_SKIPDIRS="node_modules,vendor"
export SEMANTIC_SEARCH_MODEL="Xenova/all-MiniLM-L6-v2"

All config options

Alternative models

CLI Commands

# Start the MCP server (default — for AI agents to connect)
semantic-search-mcp

# Print config snippets for your AI agent
semantic-search-mcp init

# Pre-build the index (optional, happens automatically on first use)
semantic-search-mcp index

# Clear the index cache
semantic-search-mcp clean

# Help
semantic-search-mcp --help

How It Works

1. Walk the workspace — find all code files matching the configured extensions

2. Chunk files — split large files into manageable pieces (default: 300 lines per chunk, max 4 per file)

3. Embed with ONNX — run each chunk through all-MiniLM-L6-v2 locally (384-dimensional vectors)

4. Cache — save the index to disk for instant restarts

5. Search — embed the query, compute cosine similarity against all chunks, return top matches

Everything runs on your machine. No API calls, no telemetry, no data leaves your computer.

Score Interpretation

Supported Languages

The default config indexes files with these extensions: .php, .js, .jsx, .ts, .tsx, .vue, .py, .rb, .go, .rs, .java, .cs, .swift, .kt, .css, .scss, .less, .blade.php, .mjs, .cjs

Customize via .semantic-search.json or SEMANTIC_SEARCH_EXTENSIONS env var.

Requirements

• Node.js >= 18.0.0

• ~80MB disk for the embedding model (first run)

• ~50-100MB disk for the index cache (varies by project size)

License

MIT

Related

• Cursor's semantic search blog — 12.5% better accuracy with semantic search

• sturdy-dev/semantic-code-search — Python CLI, per-function embeddings

• @xenova/transformers — ONNX models in JavaScript