🧠I Made a Semantic Search MCP for Claude Code
→ semantic-search-mcp on GitHub
🎥 Watch the demo video
The Search Capability Gap
Claude Code is excellent at reasoning and code generation, but its search capabilities feel handicapped compared to what’s possible. When I ask it to explore my codebase, it operates at maybe 50% of its potential.
Me: “Show me how authentication works in this project”
Claude Code: runs grep, finds 847 text matches, takes several iterations to piece together the flow
Meanwhile, Cursor IDE has this almost magical intuition for finding relevant code. Ask “show me auth patterns” and it instantly connects your login components, JWT middleware, and session handling - even when they use completely different terminology.
The difference isn’t intelligence - it’s indexing approach. Cursor uses semantic indexing while Claude Code relies on traditional text search. That’s the handicap.
Plus, Claude Code has real advantages: better pricing on max subscriptions, superior terminal workflows, and automation capabilities that make development faster. It just needs better search indexing to unlock its full potential.
Bridging the Intelligence Gap
So I built semantic-search-mcp - a simple MCP plugin that gives Claude Code Cursor-level semantic understanding.
Instead of text matching, it uses vector embeddings to understand what code actually does:
- Ask “How do users log in?” → Finds login forms, auth middleware, session logic, password utilities
- Ask “Show me error handling” → Discovers try/catch blocks, error classes, logging patterns
- Ask “Database relationships” → Locates models, queries, migrations, schema files
The magic: Claude Code finally understands your codebase conceptually, connecting related code across different files and languages.
How It Works (The Simple Version)
ChromaDB + Vector Embeddings: Your code gets converted into mathematical representations that understand meaning, not just text. So authenticate()
, login()
, and verifyCredentials()
become conceptually linked.
Smart Chunking: Keeps functions and classes together instead of chopping them randomly. Context matters.
MCP Integration: Plugs directly into Claude Code - no special commands needed, just ask natural questions.
Setup: 5 Minutes to Cursor-Level Search
# 1. Clone and setup
git clone https://github.com/freiholtz/semantic-search-mcp
cd semantic-search-mcp && uv sync
# 2. Add your project
uv run manage.py
> add /path/to/your/project
> json 1
# 3. Connect to Claude Code (copy the command from step 2)
claude mcp add semantic-search --env WORKSPACE_PATH="/path/to/your/project" -- uv run --directory /path/to/semantic-search-mcp scripts/run_server.py
That’s it. Claude Code now automatically uses semantic search when you ask conceptual questions.
The Before & After
Before: “Show me auth code” → grep returns 847 matches, 20 minutes of hunting
After: “Show me auth code” → 5 relevant files found instantly, complete understanding
Claude Code just got Cursor superpowers.
Why This Matters
Claude Code has excellent reasoning and great pricing/workflow advantages, but its search indexing approach leaves performance on the table. Meanwhile, Cursor’s almost magical code discovery comes from semantic indexing, not superior AI.
This MCP plugin levels the playing field by giving Claude Code the same indexing advantages.
Perfect for developers who:
- Love Claude Code’s terminal workflow and pricing but want better search
- Work with large codebases where traditional search takes too long
- Want completely local semantic search (no API keys required)
- Prefer Claude’s reasoning but envy Cursor’s code discovery
Try It
5-minute setup, immediate difference: github.com/freiholtz/semantic-search-mcp
Now Claude Code can instantly understand your codebase architecture instead of piecing it together through multiple grep iterations.
Claude Code just unlocked its full potential. ✨