The Elasticsearch MCP Server connects MCP Clients (e.g., Claude Desktop) to Elasticsearch data, enabling natural language interactions with your Elasticsearch indices. You can:
List available indices: View all Elasticsearch indices using the list_indices tool
Retrieve field mappings: Get mappings for a specific index with the get_mappings tool
Perform searches: Execute Elasticsearch queries using the Query DSL with the search tool (highlights enabled by default)
Get shard information: Retrieve shard details using the get_shards tool
Provides access to Elasticsearch indices, allowing users to list indices, inspect field mappings, and execute search queries using full Query DSL capabilities with automatic highlighting.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Elasticsearch MCP Server search for recent error logs from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This MCP server is deprecated and will only receive critical security updates going forward. It has been superseded by theElastic Agent Builder MCP endpoint, which is available in Elastic 9.2.0+ and Elasticsearch Serverless projects.
The Elasticsearch MCP Server connects your AI agents to Elasticsearch data using the Model Context Protocol (MCP). It enables natural language interactions with your Elasticsearch indices, allowing agents to query, analyze, and retrieve data without custom APIs.
Follow these steps to deploy and configure the Elasticsearch MCP Server container image from AWS Marketplace.
Before you start, ensure you have:
An Elasticsearch cluster (version 8.x or 9.x) accessible from your AWS environment
Elasticsearch authentication credentials:
Docker installed and running in your AWS environment (for example, on an EC2 instance or in a container service)
An MCP client configured (such as Claude Desktop, Cursor, VS Code, or another MCP-compatible tool)
Network connectivity between your deployment environment and your Elasticsearch cluster
These instructions apply to Elasticsearch MCP Server 0.4.0 and later. For versions 0.3.1 and earlier, refer to the README for v0.3.1.
The Elasticsearch MCP Server is provided as a Docker container image available from AWS Marketplace. You can run it using either the stdio protocol (for direct client connections) or the streamable-HTTP protocol (for web-based integrations).
The server supports two protocols:
stdio: Direct communication between the MCP client and server. Use this when your client supports stdio and runs in the same environment.
streamable-HTTP: HTTP-based protocol recommended for web integrations, stateful sessions, and concurrent clients.
Note: Server-Sent Events (SSE) is deprecated. Use streamable-HTTP instead.
Use the stdio protocol when your MCP client connects directly to the server process.
Set the following environment variables:
ES_URL: The URL of your Elasticsearch cluster (for example, https://your-cluster.es.amazonaws.com:9200)
For authentication, use one of these options:
API key: Set ES_API_KEY to your Elasticsearch API key
Basic authentication: Set ES_USERNAME and ES_PASSWORD to your Elasticsearch credentials
(Optional) ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification when connecting to Elasticsearch. Only use this for development or testing environments.
Start the MCP server in stdio mode:
docker run -i --rm \
-e ES_URL \
-e ES_API_KEY \
docker.elastic.co/mcp/elasticsearch \
stdioAdd this configuration to your Claude Desktop configuration file:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "ES_URL",
"-e", "ES_API_KEY",
"docker.elastic.co/mcp/elasticsearch",
"stdio"
],
"env": {
"ES_URL": "<elasticsearch-cluster-url>",
"ES_API_KEY": "<elasticsearch-API-key>"
}
}
}
}Replace <elasticsearch-cluster-url> with your Elasticsearch cluster URL and <elasticsearch-API-key> with your API key.
Use the streamable-HTTP protocol for web-based integrations or when you need to support multiple concurrent clients.
Set the same environment variables as the stdio protocol:
ES_URL: The URL of your Elasticsearch cluster
For authentication, use one of these options:
API key: Set ES_API_KEY to your Elasticsearch API key
Basic authentication: Set ES_USERNAME and ES_PASSWORD to your Elasticsearch credentials
(Optional) ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification
Start the MCP server in HTTP mode:
docker run --rm \
-e ES_URL \
-e ES_API_KEY \
-p 8080:8080 \
docker.elastic.co/mcp/elasticsearch \
httpThe streamable-HTTP endpoint is available at http://<host>:8080/mcp. A health check endpoint is available at http://<host>:8080/ping.
If you're using Claude Desktop (free edition) which only supports the stdio protocol, use mcp-proxy to bridge stdio to streamable-HTTP:
Install mcp-proxy:
uv tool install mcp-proxyFor alternative installation options, refer to mcp-proxy/README.md.
Add this configuration to Claude Desktop:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "/<home-directory>/.local/bin/mcp-proxy",
"args": [
"--transport=streamablehttp",
"--header", "Authorization", "ApiKey <elasticsearch-API-key>",
"http://<mcp-server-host>:<mcp-server-port>/mcp"
]
}
}
}Replace <home-directory>, <elasticsearch-API-key>, <mcp-server-host>, and <mcp-server-port> with your values.
After configuring your MCP client, verify the connection works:
Start your MCP client (for example, Claude Desktop or Cursor).
Check that the Elasticsearch MCP Server appears in your available MCP servers.
Test a simple query through your agent interface to confirm it can access your Elasticsearch indices.
If the connection fails, verify:
Your Elasticsearch cluster URL is correct and accessible from your AWS environment
Your authentication credentials are valid and have the necessary permissions
Network connectivity exists between the container and your Elasticsearch cluster (check security groups and network ACLs)
Docker is running and the container started successfully (check container logs with docker logs <container-id>)
Monitor the health and proper function of the Elasticsearch MCP Server using these methods:
Verify the container is running:
docker ps | grep elasticsearch-mcp-serverThe container should appear in the list with a status of Up.
If you're using the streamable-HTTP protocol, test the health check endpoint:
curl http://<host>:8080/pingA successful response returns pong, indicating the server is running and healthy.
View container logs to identify any issues:
docker logs <container-id>Look for error messages related to:
Elasticsearch connection failures
Authentication errors
Network connectivity issues
Test connectivity to your Elasticsearch cluster from the container:
docker exec <container-id> curl -k -u <username>:<password> <ES_URL>Or with an API key:
docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>A successful response indicates the container can reach your Elasticsearch cluster.
The Elasticsearch MCP Server handles authentication credentials securely:
API keys and passwords: Stored only in environment variables passed to the container. They are not persisted to disk or logged.
Environment variables: Set when you run the container. Use AWS Secrets Manager or AWS Systems Manager Parameter Store to manage credentials securely in production environments.
In transit: The MCP server communicates with Elasticsearch over HTTPS when your ES_URL uses the https:// protocol. Ensure your Elasticsearch cluster has SSL/TLS enabled.
At rest: The container does not store data locally. All data remains in your Elasticsearch cluster, which uses your cluster's encryption settings.
Rotate API keys regularly (every 30-90 days for production environments)
Use API keys with minimal required permissions (read-only access to specific indices when possible)
Never commit credentials to version control or share them in logs
Use AWS Secrets Manager or Parameter Store to inject credentials at runtime instead of hardcoding them
The Elasticsearch MCP Server runs as a container in your AWS environment. Consider these AWS service quotas:
EC2 instance limits: If running on EC2, ensure your instance type supports your expected workload
Elastic Container Service (ECS): If using ECS, review ECS service quotas
Elastic Kubernetes Service (EKS): If using EKS, review EKS service quotas
Network bandwidth: Ensure sufficient network bandwidth between your container and Elasticsearch cluster
To request quota increases, use the AWS Service Quotas console or refer to the AWS General Reference Guide.
Once connected, the MCP server provides these tools to your agent:
list_indices: List all available Elasticsearch indices
get_mappings: Get field mappings for a specific Elasticsearch index
search: Perform an Elasticsearch search using query DSL
esql: Execute an ES|QL query
get_shards: Get shard information for all or specific indices
Your agent can use these tools to interact with your Elasticsearch data through natural language conversations.
Learn about AI-powered features available in the Elastic platform
Explore Agent Builder for building custom AI agents with Elasticsearch
Get field mappings for a specific Elasticsearch index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to get mappings for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Get field mappings', implying read-only but not disclosing permissions, side effects, or behavior like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention what the response contains; it is adequate but minimal for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'index' has a description; the tool description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'field mappings' for a specific Elasticsearch index, clearly distinguishing from siblings like create_mapping or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; for example, it doesn't explain how it differs from create_mapping or search in terms of use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Elasticsearch indices
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read operation, it doesn't specify whether this requires special permissions, returns paginated results, includes hidden/system indices, or provides any metadata beyond names. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple listing tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation without output schema, the description provides the minimum viable information about what the tool does. However, given the lack of annotations and sibling tools with potentially overlapping functionality, more context about when to use this versus alternatives would be helpful. The description is complete enough for basic understanding but leaves operational context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't mention parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema handles all parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available Elasticsearch indices'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_mappings' or 'search' - it's unclear if this is a simple listing versus more detailed metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_mappings' or 'search'. There's no indication of whether this is for administrative purposes, discovery, or as a prerequisite for other operations. The agent must infer usage context from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to search | |
| queryBody | Yes | Complete Elasticsearch query DSL object that can include query, size, from, sort, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only mentions highlights are always enabled. No disclosure of read-only nature, error handling, pagination, or required permissions. With no annotations, more behavioral detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action. No wasted words, though could be expanded with important behavioral notes without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of Elasticsearch searches (query DSL), the description lacks return format, pagination behavior, and error context. Incomplete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes both parameters. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs an Elasticsearch search with query DSL, identifying the specific verb and resource. Distinguishes from sibling tools that handle index management, bulk operations, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings (e.g., bulk, list_indices) or when not to use it. Lacks prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_mappingslist_indicessearchScored across 3 tools
Each tool has a clearly distinct purpose: get_mappings retrieves field mappings for a specific index, list_indices enumerates all indices, and search performs query-based searches. There is no overlap in functionality, making tool selection unambiguous.
All tool names follow a consistent verb_noun pattern (get_mappings, list_indices, search), with clear and descriptive verbs that align with their actions. No deviations or mixed conventions are present.
With only 3 tools, the set feels thin for an Elasticsearch server, as it lacks essential operations like creating/deleting indices, updating mappings, or performing CRUD operations on documents. While the tools are well-defined, the count is borderline for the domain's scope.
There are significant gaps in the tool surface for Elasticsearch functionality. Missing operations include index creation/deletion, document indexing/updating/deleting, and cluster management. This incompleteness will likely cause agent failures when attempting full workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Build and manage AI-native customer support agents from Claude or any MCP client.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
