Semantic Code Search MCP Server

This project includes a Model Context Protocol (MCP) server that exposes the indexed data through a standardized set of tools. This allows AI coding agents to interact with the indexed codebase in a structured way.

Prerequisites

You must index your code base with the Semantic Code Search Indexer found here: https://github.com/elastic/semantic-code-search-indexer

Index model expected by this MCP server

This MCP server expects the locations-first index model from indexer PR elastic/semantic-code-search-indexer#135:

• <index> stores content-deduplicated chunk documents (semantic search + metadata).
• <index>_locations stores one document per chunk occurrence (file path + line ranges + directory/git metadata) and references chunks by chunk_id.

Several tools query <index>_locations and join back to <index> via chunk_id (typically using mget).

Running with Docker

The easiest way to run the MCP server is with Docker. The server is available on Docker Hub as simianhacker/semantic-code-search-mcp-server.

To ensure you have the latest version of the image, run the following command before running the server:

docker pull simianhacker/semantic-code-search-mcp-server

HTTP Mode

This mode is useful for running the server in a containerized environment where it needs to be accessible over the network.

docker run --rm -p 3000:3000 \
  -e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
  simianhacker/semantic-code-search-mcp-server

Replace <your_elasticsearch_endpoint> with the actual endpoint of your Elasticsearch instance.

STDIO Mode

This mode is useful for running the server as a local process that an agent can communicate with over stdin and stdout.

With Elasticsearch Endpoint:

docker run -i --rm \
  -e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
  simianhacker/semantic-code-search-mcp-server \
  node dist/src/mcp_server/bin.js stdio

With Elastic Cloud ID:

docker run -i --rm \
  -e ELASTICSEARCH_CLOUD_ID=<your_cloud_id> \
  -e ELASTICSEARCH_API_KEY=<your_api_key> \
  simianhacker/semantic-code-search-mcp-server \
  node dist/src/mcp_server/bin.js stdio

The -i flag is important as it tells Docker to run the container in interactive mode, which is necessary for the server to receive input from stdin.

Connecting a Coding Agent

You can connect a coding agent to the server in either HTTP or STDIO mode.

HTTP Mode: For agents that connect over HTTP, like the Gemini CLI, you can add the following to your ~/.gemini/settings.json file:

{
  "mcpServers": {
    "Semantic Code Search": {
      "trust": true,
      "httpUrl": "http://localhost:3000/mcp/",
    }
  }
}

STDIO Mode: For agents that connect over STDIO, you need to configure them to run the Docker command directly. Here's an example for the Gemini CLI in your ~/.gemini/settings.json file:

{
  "mcpServers": {
    "SemanticCodeSearch": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ELASTICSEARCH_CLOUD_ID=<your_cloud_id>",
        "-e", "ELASTICSEARCH_API_KEY=<your_api_key>",
        "-e", "ELASTICSEARCH_INDEX=<your_index>",
        "simianhacker/semantic-code-search-mcp-server",
        "node", "dist/src/mcp_server/bin.js", "stdio"
      ]
    }
  }
}

Remember to replace the placeholder values for your Cloud ID, API key, and index name.

Setup and Installation

1. Prerequisites

• Node.js (v20 or later)
• npm
• An running Elasticsearch instance (v8.0 or later) with the ELSER model downloaded and deployed.

2. Clone the Repository and Install Dependencies

git clone <repository-url>
cd semantic-code-search-mcp-server
npm install

3. Configure Environment Variables

Copy the .env.example file and update it with your Elasticsearch credentials.

cp .env.example .env
``

... [View full README on GitHub](https://github.com/elastic/semantic-code-search-mcp-server#readme)