→ 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.

# 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. ✨