home / mcp / semantic search mcp server

Semantic Search MCP Server

Delivers hybrid semantic search over codebases via an MCP server, combining BM25 keyword retrieval with vector search for Claude Code.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "camilojourney-codesight": {
      "command": "python",
      "args": [
        "-m",
        "semantic_search_mcp"
      ],
      "env": {
        "SEMANTIC_SEARCH_DATA_DIR": "~/.semantic-search/data"
      }
    }
  }
}

You can run a Semantic Search MCP Server to provide Claude Code with hybrid semantic search capabilities over your codebase. It combines keyword matching with vector search for fast, accurate code retrieval and supports practical indexing, testing, and usage within Claude Code.

How to use

You connect to the server from your MCP client and perform common search and index operations. Start by ensuring the server is running, then use the client to index repositories, search across codebases, and check index status. The workflow typically involves starting the server locally, indexing your code, and issuing search queries against your indexed data.

How to install

Prerequisites: Python 3.11+ and a working Python environment. You will also use the MCP client within Claude Code to interact with the server.

# Install the MCP server package in editable mode from the local project
cd semantic_search_MCP
pip install -e ".[dev]"

# Optional: verify the server can be inspected with an MCP inspector if you want to test locally
npx @modelcontextprotocol/inspector python -m semantic_search_mcp

# Connect to Claude Code (example command shown for integration)
claude mcp add semantic-search -- python -m semantic_search_mcp

Additional content

Configuration is managed via environment variables and the server exposes a minimal set of runtime options for indexing and retrieval. The primary environment variable shown is the data directory where all indexes are stored.

Environment variables you will use when running the server:

{
  "SEMANTIC_SEARCH_DATA_DIR": "~/.semantic-search/data"
}

Available tools

search

Hybrid search that combines semantic vector retrieval with BM25 keyword matching. Auto-indexes if needed.

index

Build or rebuild the search index for a given repository path.

status

Check if a repository is indexed and determine if the index is stale.