Elasticsearch Server

Connect Claude Code to Elasticsearch clusters for executing search queries, exploring index mappings, and analyzing data through the Model Context Protocol.

When to Use This MCP Server

Connect this server when you need to:

• Execute Elasticsearch queries including full-text search, aggregations, and ES|QL directly from Claude Code while developing search features
• Explore index mappings, field types, and shard distribution to understand your Elasticsearch cluster structure during application development
• Debug search relevance issues by testing query variations and analyzing scoring explanations without switching to Kibana or curl

Consider alternatives when:

• You need Kibana visualization features like dashboards, lens, or canvas for presenting search analytics to stakeholders
• Your data is stored in a relational database like PostgreSQL or MySQL, where the corresponding database MCP servers are more appropriate

Quick Start

Configuration

Copy
name: elasticsearch-server
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect elasticsearch-server

Available Tools

search:             Execute search queries with full Query DSL support and pagination
get-mapping:        Retrieve index mappings showing field definitions and analyzer config
list-indices:       Enumerate indices with health status, document counts, and storage size
esql-query:         Run ES|QL queries for SQL-like data analysis on Elasticsearch indices
get-shard-info:     Display shard allocation, sizes, and cluster health information

Core Concepts

Elasticsearch MCP Server Overview

Aspect	Details
Transport	Docker container running elasticsearch MCP server via stdio communication
Authentication	Elasticsearch API key for secure cluster access and authorization
Query Support	Full Query DSL, ES
Index Management	Read-only index metadata including mappings, settings, and statistics
Cluster Info	Shard allocation, node health, and cluster-wide statistics access

Elasticsearch MCP Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [Docker: elasticsearch-mcp]
                              |
                              v
                     [Elasticsearch REST API]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Search    [Index     [Cluster
               API]      Mapping]   Health]
                    \         |         /
                     [Elasticsearch Cluster]
                       Nodes | Shards | Data

Configuration

Parameter	Type	Default	Description
ES_URL	string	required	Elasticsearch cluster URL (e.g., https://cluster.elastic.cloud:9243)
ES_API_KEY	string	required	Elasticsearch API key for authentication and authorization
default_index	string	none	Default index pattern to query when not explicitly specified
max_hits	integer	100	Maximum number of search results to return per query
request_timeout	integer	30000	Timeout in milliseconds for Elasticsearch API requests

Best Practices

1. Use API Keys with Minimal Scope - Create Elasticsearch API keys restricted to the specific indices and operations your development work requires. Avoid using superuser API keys that grant unrestricted cluster access.

2. Inspect Mappings Before Writing Queries - Use get-mapping to understand field types and analyzers before constructing search queries. Querying a keyword field with match or a text field with term produces unexpected results.

3. Test Queries with Small Result Sets - Start with low max_hits values when testing new queries. This provides fast feedback on query structure and relevance while avoiding memory pressure from large result sets.

4. Use ES|QL for Analytical Queries - For aggregation-heavy analysis, ES|QL provides a more intuitive SQL-like syntax compared to JSON Query DSL. It is especially useful for computing statistics, grouping, and filtering without complex nested JSON.

5. Monitor Shard Health During Development - Periodically check get-shard-info to ensure your development cluster is healthy. Unassigned shards or red indices indicate problems that can cause search failures or data loss.

Common Issues

1. Connection Refused or Timeout - Verify the ES_URL is correct and includes the protocol (https://) and port. Cloud-hosted clusters typically use port 9243 for HTTPS, while local clusters default to 9200.

2. API Key Returns 403 Forbidden - The API key may lack permissions for the requested index or operation. Check the key's role assignments in Elasticsearch and ensure it includes the necessary index privileges.

3. Docker Container Cannot Reach Cluster - When running the MCP server in Docker, ensure the container can resolve the Elasticsearch hostname. For local clusters, use host.docker.internal instead of localhost in the ES_URL.