Elasticsearch MCP Server

An MCP (Model Context Protocol) server that gives AI assistants like Claude direct access to Elasticsearch. Search, aggregate, and retrieve documents from any index — all exposed as MCP tools over a Streamable HTTP transport.

Quickstart

With Docker (recommended)

docker build -t elasticsearch-mcp .
docker run -e ES_URL=http://host.docker.internal:9200 -p 3100:3100 elasticsearch-mcp

Without Docker

Requires Node.js 22+.

npm install
npm run build
ES_URL=http://localhost:9200 npm start

Connect to Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "elasticsearch": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp"
    }
  }
}

Sample prompts

Once connected, try asking Claude things like:

• "What indices do I have? Pick the most interesting one and tell me what fields are available."
• "Search the logs index for timeout errors in the last 24 hours and summarize what's going wrong."
• "Which users have the most failed login attempts? Break it down by country."
• "Find all documents mentioning 'rate limit' and show me the top 5 with highlights."
• "How many orders were placed each month this year? Plot the trend."
• "Compare how often these product names appear across the catalog: 'widget', 'gadget', 'gizmo', 'doohickey'."
• "Pull up document abc-123 and give me a plain-English summary."
• "What are the most common values in the status field? Are any of them suspicious?"

Tools

list_indices

List all Elasticsearch indices with doc counts, storage size, health, and status. Accepts an optional glob pattern to filter index names.

get_mapping

Get field names and types for an index.

search

Full-text search with query modes: match, match_phrase, multi_match, query_string. Supports filters, sorting, pagination, highlighting, field selection, and minimum score thresholds.

count

Count documents matching a query with optional filters.

multi_count

Count multiple phrases in one call using msearch. Useful for co-occurrence analysis — can require an additional term to co-occur with each phrase.

get_document

Retrieve a single document by _id or document_id field value. Long text fields are truncated by default.

aggregate

Run aggregations on an index:

• terms — Top values by frequency
• stats — min/max/avg/sum/count for numeric fields
• date_histogram — Monthly bucketing for date fields
• top_hits — Sample documents per bucket
• cardinality — Distinct value count
• filter — Filtered document count

Supports sub-aggregations for nested analysis (e.g., terms + stats).

Configuration

Variable	Default	Description
ES_URL	http://localhost:9200	Elasticsearch URL
ES_API_KEY	—	API key for Elasticsearch authentication (optional)
PORT	3100	HTTP port the server listens on

Endpoints

Path	Method	Description
/mcp	POST	MCP protocol (Streamable HTTP transport)
/health	GET	Health check (returns ok)

Semantic & Hybrid Search

The search tool also supports two additional modes for indices with dense_vector fields:

• semantic — kNN vector search using a built-in all-MiniLM-L6-v2 embedding model (384 dimensions). No external embedding API needed.
• hybrid — Runs keyword + semantic in parallel and fuses results with Reciprocal Rank Fusion (k=60).

Set search_mode to semantic or hybrid and specify the embedding_field (defaults to text_embedding).

The embedding model is downloaded on first use and cached locally. The Docker image pre-downloads it at build time. Use TRANSFORMERS_CACHE to control where the model is stored.

Variable	Default	Description
TRANSFORMERS_CACHE	(system default)	Directory to cache the embedding model