Semantic Search Mcp

Semantic code search for AI coding agents. Local embeddings. No API keys. No data leaves your machine.

npm version node

Your AI agent (opencode, Claude) can grep for exact words - but semantic-search-mcp lets it find code by meaning. Ask "where do we handle authentication?" and it returns auth.controller.ts, login.component.jsx, auth.config.php - even if the word "handle" doesn't appear in any of them.

80MB model. Runs 100% locally. Powered by bge-small-en-v1.5.

Grep vs. Semantic Search

On a 6,900-file codebase:

Query	Grep	semantic-search-mcp
"where users upload avatars"	30+ results, unsorted, mixed noise	5 ranked, best match first (0.835)
"how error logs are sent"	0 results (no file contains "sent" + "logs")	5 results across handlers, mailers, config
"scheduled task for cleanup"	2 results (only exact matches)	5 results - cron jobs, queues, commands
Time	~30s searching + scanning	2 seconds from cache

---

Quick Start (3 steps)

1. Install

npm install -g semantic-search-mcp

2. Index your project

cd /path/to/your-project
semantic-search-mcp index

The folder you run this from gets indexed. Shows live progress:

████████████████░░░░░░ 70% (5200/7368) - ~120s remaining
██████████████████████ Done! 7368 chunks in 726s.

First run downloads the model (~80MB, one-time) + indexes your code (5-15 min depending on project size). After that, the cache is saved and restarts are instant.

Multiple projects? Run cd /project-a && semantic-search-mcp index, then cd /project-b && semantic-search-mcp index. Each project gets its own cache automatically.

3. Connect your AI agent

Add this to your opencode.json (or opencode.jsonc) in the project root:

{
  "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"]
    }
  }
}

Claude Code (CLI) - add .mcp.json to your project root:

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

Restart your AI agent. Done. Searches are instant - cache was already built.

---

FAQ

Which folder gets indexed?

The folder you cd into before running semantic-search-mcp index. It's your current working directory. When opencode or Claude starts the MCP server, that same folder gets used automatically.

I have 3 projects. Do I index each one?

Yes. Each project has its own cache:

project-a/.semantic-search/cache/index.json
project-b/.semantic-search/cache/index.json
project-c/.semantic-search/cache/index.json

Where is the cache stored?

{your-project}/.semantic-search/cache/index.json

About 50-100MB per project. Survives PC restarts, Git pulls, everything. It's just files on disk. Only cleared if you run semantic-search-mcp clean.

How do I remove the cache?

semantic-search-mcp clean

Do I need to re-index after code changes?

No. But if you add many new files or want fresh results: semantic-search-mcp clean && semantic-search-mcp index.

What model does it use?

Xenova/bge-small-en-v1.5 by default (80MB, 384-dim, retrieval-optimized). You can switch models via semantic-search-mcp config.

Is my code sent anywhere?

No. Everything runs on your machine - model, embeddings, search. Zero network calls after model download.

---

CLI Commands

semantic-search-mcp index    # Index current folder (live progress bar)
semantic-search-mcp config   # Interactive TUI to pick extensions, model, thresholds
semantic-search-mcp clean    # Remove index cache
semantic-search-mcp init     # Print opencode/Claude config snippet
semantic-search-mcp           # Start the MCP server (used by AI agents)
semantic-search-mcp --help   # All commands

Configuration

Run semantic-search-mcp config for interactive setup (checkboxes for extensions, searchable model picker, number inputs).

Or create .semantic-search.json in your project root:

{
  "extensions": [".php", ".js", ".jsx", ".ts", ".tsx"],
  "skipDirs": ["node_modules", "vendor", ".git", "dist"],
  "model": "Xenova/bge-small-en-v1.5",
  "chunkThreshold": 300,
  "maxChunksPerFile": 4
}

Or env vars: SEMANTIC_SEARCH_EXTENSIONS=.php,.js, SEMANTIC_SEARCH_MODEL=Xenova/bge-small-en-v1.5

All options

Key	Default
extensions	20+ code extensions	File types to index
skipDirs	node_modules, vendor, .git, ...	Directories to skip
model	Xenova/bge-small-en-v1.5	HuggingFace embedding model
cacheDir	.semantic-search/cache	Where cache is stored (per project)
chunkThreshold	300	Lines before splitting file
maxChunksPerFile	4	Max chunks per large file
maxResults	50	Max search results
defaultLimit	10	Default results per query

How It Works

1. Scan - walk your project, find code files
2. Extract - split at function/class boundaries (PHP, JS, TS, Python, Go, Rust, Java)
3. Embed - run each chunk through a local ONNX model (384-dim vectors)
4. Cache - save everything to disk
5. Search - embed your query, find closest matches via cosine similarity

License

MIT