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 provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't describe how it behaves: no information about permissions required, rate limits, error conditions, response format, or whether it's a read-only operation. The description is minimal and lacks behavioral context.
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 states the core purpose without unnecessary words. It's appropriately sized for a simple tool with one parameter and is front-loaded with essential information.
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 tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'field mappings' means in practice, what format the response will be in, or any behavioral characteristics. Given the lack of structured data, the description should provide more context about what users can expect from this 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 description coverage is 100% with the single parameter 'index' well-documented in the schema. The description adds no additional parameter semantics beyond what's already in the schema, so it meets the baseline for high schema coverage without adding value.
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 action ('Get') and resource ('field mappings for a specific Elasticsearch index'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'list_indices' or 'search', but the specificity of 'field mappings' provides some implicit differentiation.
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 'list_indices' or 'search'. It mentions 'specific Elasticsearch index' which implies context but doesn't specify prerequisites, constraints, or typical use cases for retrieving mappings.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by stating 'Highlights are always enabled', which informs about a default behavior not evident from the schema. However, it lacks details on other critical aspects like permissions, rate limits, error handling, or response format, leaving gaps in transparency for a search operation.
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 extremely concise with two sentences that directly convey the tool's function and a key behavioral trait. It is front-loaded with the primary purpose and avoids any unnecessary words, making it efficient and easy to parse.
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 a search tool with two parameters (including a nested object) and no output schema or annotations, the description is somewhat incomplete. It covers the basic action and a behavioral detail but omits information on return values, error cases, or integration with sibling tools, which could hinder the agent's ability to use it effectively in varied contexts.
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 schema description coverage is 100%, so the schema already documents both parameters ('index' and 'queryBody') adequately. The description adds minimal semantics by implying the use of Elasticsearch query DSL but doesn't provide additional syntax, examples, or constraints beyond what the schema specifies, meeting the baseline for high coverage.
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 action ('Perform an Elasticsearch search') and the resource ('with the provided query DSL'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'get_mappings' or 'list_indices', which would require mentioning that this tool executes actual search queries rather than retrieving metadata or listings.
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 such as 'get_mappings' or 'list_indices'. It mentions that 'Highlights are always enabled', which hints at a behavioral trait but doesn't clarify usage contexts, prerequisites, or exclusions, leaving the agent without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/elastic/mcp-server-elasticsearch'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
