home / mcp / claude context local mcp server

Claude Context Local MCP Server

Code search MCP for Claude Code. Make entire codebase the context for any coding agent. Embeddings are created and stored locally. No API cost.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "farhanaliraza-claude-context-local": {
      "command": "claude",
      "args": [
        "mcp",
        "add",
        "code-search",
        "--scope",
        "user",
        "--",
        "uv",
        "run",
        "--directory",
        "~/.local/share/claude-context-local",
        "python",
        "mcp_server/server.py"
      ],
      "env": {
        "HF_HUB_OFFLINE": "1"
      }
    }
  }
}

You can run a local MCP server that lets Claude Code talk to your own code context. This setup keeps all embeddings and indexing on your machine, speeds up searches, and preserves privacy while giving you seamless semantic code access inside Claude Code.

How to use

Register the MCP server as a stdio endpoint so Claude Code can talk to your local code search and indexing tools. Then index your codebase and use Claude Code to query and explore your code as you work.

Step by step you will: register the MCP server, index your projects, and interact with Claude Code to search and retrieve code results using natural language queries.

How to install

Prerequisites you need on your machine before installing the MCP server are Python 3.12 or newer and a working shell with curl or wget available.

Follow these steps to install and set up the MCP server and its runtime environment.

# 1) Install the MCP server and runtime
curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

# If curl is unavailable, use wget as an alternative
wget -qO- https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

After installation, register the MCP server as a stdio endpoint for Claude Code using the provided command.

Additional setup steps

The installer will set up a local project directory at ~/.local/share/claude-context-local, install required Python dependencies, and download the EmbeddingGemma model for local embeddings.

To prepare for indexing, ensure your codebase is accessible and not ignored by the default ignore patterns.

Using the MCP server with Claude Code

1) Register the MCP server as a stdio endpoint inside Claude Code using the exact command shown in the Quick Start guide.

claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

2) Open Claude Code and ask to index your codebase. Claude Code will communicate with the local MCP server to build and use the semantic index for fast, relevant results.

3) When you search, Claude Code uses the local embeddings and FAISS index to return results with precise locations in your files.

Configuration and environment

Key configuration and runtime details are available within the setup workflow. The default storage for models and indices is ~/.claude_code_search, which holds the downloaded EmbeddingGemma model, the FAISS index, and related metadata.

Troubleshooting

Common issues you might encounter and how to address them: verify dependencies with uv sync, ensure internet access during first model download, and confirm there is enough disk space for the model (~1.2–2 GB). If FAISS GPU acceleration is not used, verify that NVIDIA drivers and nvidia-smi are available, or run without GPU support.

If you encounter search issues, confirm that the first indexing step completed successfully and that your codebase is not excluded by ignore patterns.

Notes

All indexing and embeddings are performed locally. No data leaves your machine unless you choose to share results externally. The MCP server is designed to be run inside Claude Code via the stdio channel for a seamless workflow.

Tools and endpoints overview

This MCP server exposes functionality to enable semantic code search, local indexing, and tight integration with Claude Code. You can index multiple projects, query them through natural language, and retrieve precise code locations with rich metadata.

Available tools

MCP integration

Directly connect Claude Code to the local MCP server to enable semantic code search and retrieval.

Incremental indexing

Use Merkle-based change detection to incrementally index changes in your codebase.