semantic-code

semantic-code-mcp is a Python-based MCP server that provides semantic code search for Claude Code. It indexes your codebase by chunking source files with tree-sitter, generating embeddings with a sentence-transformers model, and storing vectors in LanceDB. The server supports Python, Rust, and Markdown, and is designed to return results ranked by semantic similarity while also allowing keyword filtering. On first use, the index is built automatically when you run a search, and indexing proceeds incrementally based on file modification times. You can engage it through Claude Code or MCP clients, using the provided tools to index a repository and then search for code by natural language descriptions or by code-related queries. The tools exposed include search_code for meaning-based retrieval, index_codebase to build or refresh an index for a project, and index_status to monitor progress. Configuration is environment-variable driven (SEMANTIC_CODE_MCP_*) and can be supplied via the MCP config or CLI hints to Claude Code.

Prerequisites:

• Python 3.9+ installed
• pip available
• Access to your project codebase to index

Installation steps:

1. Install the MCP server package via uvx (the command used in this project):

uvx semantic-code-mcp

2. (Optional) If you plan to integrate with Claude Code or other MCP clients, you can add the server to your MCP config or CLI as shown in the examples. For Claude Code integration, you would typically run:

claude mcp add --scope user semantic-code -- uvx semantic-code-mcp

3. If you need the CPU-only PyTorch embedding model (default behavior for CPU), nothing extra is required on macOS/Windows. For Linux, you can optionally configure the index as described in the README when using CUDA-free builds (see the CPU-only index example).

Note: The embedding model loads lazily on the first query, so initial searches may trigger a small delay while the model initializes.

Tips and common considerations:

• The system uses incremental indexing based on file modification times and relies on git ls-files for fast file discovery during indexing.
• Environment variables control behavior such as where indexes are stored and which embedding model to use. Example variables include SEMANTIC_CODE_MCP_CACHE_DIR and SEMANTIC_CODE_MCP_EMBEDDING_MODEL.
• If you need to override defaults or enable debugging, set SEMANTIC_CODE_MCP_DEBUG=true in your MCP config or via the Claude CLI as shown in the README.
• The MCP tools include search_code, index_codebase, and index_status. Use search_code to retrieve results with file_path, line_start, line_end, name, chunk_type, content, and score. Use index_codebase to index a project and index_status to monitor progress.
• When adding new languages, you will need a tree-sitter grammar package and a corresponding chunker subclass. The documentation provides a workflow for extending chunkers and registering them in the container.
• If you intend to run locally and want GPU acceleration, you can configure a CUDA-enabled embedding setup, but the default CPU-based embeddings are recommended for most use cases.