🔮 Semantic Search MCP

Semantic code search MCP tool for any AI agents. Gives Claude Code the intelligent search capabilities that Cursor IDE users love.

🎥 Watch the demo video

📖 Read the full story - How this bridges the Claude Code vs Cursor search capability gap

Why this exists: Cursor IDE has excellent semantic code search that makes AI agents much more effective. Claude Code uses only traditional search (find/grep), missing contextual connections. This tool brings Cursor-like semantic search capabilities to Claude Code and other AI agents.

🔒 Completely local - No API keys, no data leaves your computer
⚡ No server required - Pre-indexed collections, updates on-demand

TLDR

Clone this repo
Add a working directory path and get the MCP configuration
Add the MCP to your coding agent
Now you have semantic search. 🎉

Prerequisites

Install UV (Python package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup

1. Clone and install:

git clone <this-repo>
cd semantic-search-mcp
uv sync

2. Add a project for searching:

# Start the management tool
uv run manage.py

# Add your project (automatically analyzes first):
> add /path/to/your/project

# It will show you what files will be indexed and ask for confirmation.
# This is useful to verify the file count matches your expectations.

# Get the configuration for your AI agent:  
> json 1

3. Add to your AI agent:

For Claude Code:

# Use the command from the management tool:
claude mcp add semantic-search --env WORKSPACE_PATH="/path/to/your/project" -- uv run --directory /path/to/semantic-search-mcp scripts/run_server.py

For other MCP clients:

{
  "mcpServers": {
    "semantic-search": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/semantic-search-mcp", "scripts/run_server.py"],
      "env": {
        "WORKSPACE_PATH": "/path/to/your/project"
      }
    }
  }
}

Usage

Once installed, your AI agent will automatically use semantic search when you ask code questions:

# Just talk naturally to your agent:
"How does user authentication work in this codebase?"
"Show me the database connection logic"  
"Find error handling patterns in the code"

The agent learns from the MCP tool description to use semantic search for conceptual queries and Grep for exact matches. No special commands needed - just ask naturally!

Manual override: If you want to force the agent to use semantic search, you can mention it: "Use semantic search to find..."

Multiple Projects

This MCP tool naturally handles multiple projects in two powerful ways:

1. Search Multiple Repositories

Add semantic search for different codebases using unique names:

claude mcp add semantic-search-main --env WORKSPACE_PATH="/path/to/main-project" -- uv run --directory /path/to/semantic-search-mcp scripts/run_server.py
claude mcp add semantic-search-notes --env WORKSPACE_PATH="/path/to/dev-notes" -- uv run --directory /path/to/semantic-search-mcp scripts/run_server.py

Creates: @semantic_search_main and @semantic_search_notes tools

2. Enhanced Development Workflow

One agent can benefit from multiple semantic searches simultaneously:

Example scenario: Working on your main project but also having access to:

Your developer notes repository - General technical solutions and patterns
Related codebases - Libraries or services that integrate with your main project
Documentation repos - Internal wikis or technical guides

Even when you've added multiple repositories to Claude Code's workspace, you still need semantic search to intelligently find connections and patterns across them. Traditional grep/find can't understand conceptual relationships between codebases.

Management

Workspace commands:

add <path> - Analyze and index project (shows preview, asks confirmation)
investigate <path> - Analyze project without indexing (for planning)
json <nr> - Get configuration for existing collection

Collection commands:

info <nr> - View collection details
delete <nr> - Remove collection

Technical Info

Requirements: Python ≥3.12, UV package manager
Safe indexing: 1MB file limit, text files only (no binaries)
Smart filtering: Ignores node_modules, .venv, build artifacts
File types: Programming languages, docs (.md, .txt, .csv), configs
Performance: ChromaDB with cosine similarity, sentence-transformers

Built with UV, ChromaDB, Pydantic v2, and the official MCP SDK.

Development

Setup for contributors:

uv sync --dev  # Install dev dependencies (ruff, ty, black, etc.)
./check.sh     # Run all checks (type, format, lint, test)

Run ./check.sh before submitting changes to ensure code quality standards.

License

Free to use and modify for any purpose. If you find this useful, please credit David Freiholtz for the original implementation.

MCP Servers