Connects to Elastic products, specifically Elasticsearch, enabling natural language interaction with indices, mappings, and search capabilities.
Allows querying and managing Elasticsearch data, providing tools for listing indices, retrieving field mappings, performing searches with query DSL, and viewing shard information.
Click on "Deploy 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 show me the field mappings for the 'products' index"
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 repository contains experimental features intended for research and evaluation and are not production-ready.
Connect to your Elasticsearch data directly from any MCP Client (like Claude Desktop) using the Model Context Protocol (MCP).
This server connects agents to your Elasticsearch data using the Model Context Protocol. It allows you to interact with your Elasticsearch indices through natural language conversations.
list_indices: List all available Elasticsearch indices
get_mappings: Get field mappings for a specific Elasticsearch index
search: Perform an Elasticsearch search with the provided query DSL
get_shards: Get shard information for all or specific indices
Related MCP server: Elasticsearch MCP Server
An Elasticsearch instance
Elasticsearch authentication credentials (API key or username/password)
MCP Client (e.g. Claude Desktop)
https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
The easiest way to use Elasticsearch MCP Server is through the published npm package.
Configure MCP Client
Open your MCP Client. See the list of MCP Clients, here we are configuring Claude Desktop.
Go to Settings > Developer > MCP Servers
Click Edit Config and add a new MCP Server with the following configuration:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": [
"-y",
"@elastic/mcp-server-elasticsearch"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}Start a Conversation
Open a new conversation in your MCP Client
The MCP server should connect automatically
You can now ask questions about your Elasticsearch data
The Elasticsearch MCP Server supports configuration options to connect to your Elasticsearch:
You must provide either an API key or both username and password for authentication.
Environment Variable | Description | Required |
| Your Elasticsearch instance URL | Yes |
| Elasticsearch API key for authentication | No |
| Elasticsearch username for basic authentication | No |
| Elasticsearch password for basic authentication | No |
| Path to custom CA certificate for Elasticsearch SSL/TLS | No |
If you want to modify or extend the MCP Server, follow these local development steps.
Use the correct Node.js version
nvm useInstall Dependencies
npm installBuild the Project
npm run buildRun locally in Claude Desktop App
Open Claude Desktop App
Go to Settings > Developer > MCP Servers
Click Edit Config and add a new MCP Server with the following configuration:
{
"mcpServers": {
"elasticsearch-mcp-server-local": {
"command": "node",
"args": [
"/path/to/your/project/dist/index.js"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}Debugging with MCP Inspector
ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspectorThis will start the MCP Inspector, allowing you to debug and analyze requests. You should see:
Starting MCP inspector...
Proxy server listening on port 3000
š MCP Inspector is up and running at http://localhost:5173 šWe welcome contributions from the community! For details on how to contribute, please see Contributing Guidelines.
Here are some natural language queries you can try with your MCP Client.
"What indices do I have in my Elasticsearch cluster?"
"Show me the field mappings for the 'products' index."
"Find all orders over $500 from last month."
"Which products received the most 5-star reviews?"
The MCP Client analyzes your request and determines which Elasticsearch operations are needed.
The MCP server carries out these operations (listing indices, fetching mappings, performing searches).
The MCP Client processes the results and presents them in a user-friendly format.
Avoid using cluster-admin privileges. Create dedicated API keys with limited scope and apply fine-grained access control at the index level to prevent unauthorized data access.
You can create a dedicated Elasticsearch API key with minimal permissions to control access to your data:
POST /_security/api_key
{
"name": "es-mcp-server-access",
"role_descriptors": {
"mcp_server_role": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"index-1",
"index-2",
"index-pattern-*"
],
"privileges": [
"read",
"view_index_metadata"
]
}
]
}
}
}This project is licensed under the Apache License 2.0.
Ensure your MCP configuration is correct.
Verify that your Elasticsearch URL is accessible from your machine.
Check that your authentication credentials (API key or username/password) have the necessary permissions.
If using SSL/TLS with a custom CA, verify that the certificate path is correct and the file is readable.
Look at the terminal output for error messages.
If you encounter issues, feel free to open an issue on the GitHub repository.
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.
Get shard information for all or specific indices
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Optional index name to get shard information 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 important behavioral aspects: whether this is a read-only operation, what format the shard information returns, potential performance implications, or any limitations. The description is functional but lacks operational 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 extremely concise - a single sentence that efficiently communicates the core functionality. It's front-loaded with the main purpose and includes the scope clarification. Every word serves a purpose with no redundancy or unnecessary elaboration.
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 insufficiently complete. While concise, it doesn't explain what 'shard information' includes, the format of the response, or how to interpret the results. Given the complexity of shard management in search systems and the lack of structured documentation elsewhere, the description should provide more operational context.
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' clearly documented in the schema. The description adds minimal value beyond the schema by mentioning 'all or specific indices' which implies the optional nature of the index parameter, but doesn't provide additional context about valid index names, patterns, or special cases.
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 ('shard information'), with scope clarification ('for all or specific indices'). It distinguishes this as a retrieval operation rather than a mutation, but doesn't explicitly differentiate from similar sibling tools like 'get_mappings' or 'get_aliases' that also retrieve metadata.
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 explicit guidance on when to use this tool versus alternatives. The description mentions 'all or specific indices' which provides some context about scope, but doesn't indicate when to prefer this over other metadata retrieval tools like 'get_cluster_health' or 'list_indices', nor does it mention prerequisites or typical 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 |
|---|---|---|---|
| indexPattern | Yes | Index pattern of Elasticsearch indices to list |
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 states the action ('List all available Elasticsearch indices') but doesn't describe what 'available' means, whether it's a read-only operation, if there are rate limits, or what the output format looks like. This leaves significant gaps for a tool that interacts with a database system.
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 directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple tool and front-loaded with the core action, making it 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 interacting with Elasticsearch indices and the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'available' entails, how results are structured, or potential errors, which are crucial for an agent to use the tool effectively in a real-world context.
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%, with the parameter 'indexPattern' fully documented in the schema. The description doesn't add any meaning beyond what the schema provides, such as explaining pattern syntax or examples. With high schema coverage, the baseline score of 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?
The description clearly states the verb ('List') and resource ('all available Elasticsearch indices'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_mappings' or 'get_shards' which might also involve listing indices with different scopes or details.
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'. It lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name 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. | |
| profile | No | Whether to include query profiling information | |
| explain | No | Whether to include explanation of how the query was executed |
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 one important behavioral trait ('highlights are always enabled') that wouldn't be evident from the schema alone. However, it lacks other critical behavioral information such as pagination behavior, error handling, authentication requirements, rate limits, or what the response format looks like.
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 just two sentences that both earn their place. The first sentence states the core purpose, and the second adds important behavioral context about highlights. There's no wasted language or redundant 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 4 parameters, complex nested objects in queryBody, no output schema, and no annotations, the description is insufficiently complete. It doesn't explain what the tool returns, how results are structured, error conditions, or provide any examples of proper usage. The mention of highlights is helpful but doesn't compensate for the significant 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 schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema. It doesn't explain parameter interactions, provide examples of queryBody structure, or clarify the relationship between parameters like profile and explain.
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 ('perform') and resource ('Elasticsearch search') with the specific technology mentioned. It distinguishes from siblings like get_mappings or list_indices by focusing on search operations rather than metadata retrieval. However, it doesn't explicitly differentiate from potential search-related siblings that might exist in other contexts.
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. While it mentions 'highlights are always enabled,' this is a behavioral trait rather than usage guidance. There's no mention of prerequisites, when to choose this over other search methods, or what scenarios it's best suited for.
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.
get_mappingsget_shardslist_indicessearchScored across 4 tools
Each tool has a clearly distinct purpose targeting different aspects of Elasticsearch operations: get_mappings for field structure, get_shards for infrastructure details, list_indices for inventory, and search for querying data. There is no overlap or ambiguity between these functions.
All tool names follow a consistent verb_noun pattern (get_mappings, get_shards, list_indices, search) with clear, descriptive verbs. The naming is uniform and predictable throughout the set.
With only 4 tools, the set feels thin for an Elasticsearch server, lacking essential operations like create/update/delete indices or documents. While the tools are well-scoped, the count is borderline low for the domain's typical scope.
The tool surface has significant gaps for an Elasticsearch domain: it includes read-only operations (get, list, search) but completely misses write operations (e.g., index, update, delete), configuration management, or cluster operations. This will likely cause agent failures in common workflows.
Connect your Fulcra Context personal datastore: access your metrics, events, agent data and more
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Query your org's data in natural language ā read-only MCP access to SQL, NoSQL, files & warehouses.
