A Monday cluster check
Prompt
Every Monday at 9:00, list the indices in my Elasticsearch cluster with their shard status, flag anything that is not healthy, and save the result as elasticsearch-check.md.
Verified MCP server: Elasticsearch
The Elasticsearch MCP server, run live on a real Mac.
- Tools enumerated2026-08-03macOS 26.3.1
- Package@elastic/mcp-server-elasticsearch 0.3.1
- Self-reportedelasticsearch-mcp 0.3.1
- MCP protocol2025-06-18
- RuntimeNode v24.18.0
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Elasticsearch MCP server connects an AI assistant to a cluster you already run: it lists indices, reads field mappings, reports shard status, and runs a real query DSL search, in plain language rather than JSON you type by hand. It is Elastic's own package, published under their npm scope, with 1,717 downloads in the week ending 2026-08-01. We ran it on this Mac: npx started elasticsearch-mcp 0.3.1 over stdio, it completed the MCP handshake and listed all four tools, printed below word for word. There is no Elasticsearch cluster on this Mac, so we pointed it at a dead port on purpose, and all four of our real calls came back with the server's own connection error, which is on this page too. One thing to know before you build on it: npm carries a deprecation notice on this package, and Elastic now ships version 0.4.0 and later as a container image while pointing new users at the Agent Builder MCP endpoint inside Elasticsearch itself. [1][2][3][6]
Verification
How this MCP server was verified.
Method
We spawned the server with npx over stdio, completed the MCP initialize handshake, called tools/list, and made four real tools/call requests, one per tool. The tool table below is that capture, word for word. Working calls are pending a credential we do not have: a reachable Elasticsearch cluster, which means an ES_URL that answers plus the ES_API_KEY for it, or an ES_USERNAME and ES_PASSWORD pair. We started the server with a dummy URL on a dead port instead, so all four calls came back with the connection error printed below. That proves the server starts, speaks MCP and enumerates its whole tool set with no cluster in sight. It does not prove any tool can read data, and we do not claim it. A second run with deliberately wrong arguments and a third with an empty ES_URL gave us two more of the errors printed on this page, a fourth on a clean npm cache gave us the deprecation notice npm prints on install, and a fifth without OTEL_LOG_LEVEL listed the same four tools, which is how we know that variable is optional.
Startup banner
{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"elasticsearch-mcp","version":"0.3.1"}},"jsonrpc":"2.0","id":1}One real tool call
tools/call list_indices {"indexPattern": "*"}Error: connection failed (http://localhost:9201/)
Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 4 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| list_indicesindexPattern* | List all available Elasticsearch indices |
| get_mappingsindex* | Get field mappings for a specific Elasticsearch index |
| searchindex*queryBody*profileexplain | Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled. |
| get_shardsindex | Get shard information for all or specific indices |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": [
"-y",
"@elastic/mcp-server-elasticsearch"
],
"env": {
"ES_URL": "<your-elasticsearch-url>",
"ES_API_KEY": "<your-api-key>",
"OTEL_LOG_LEVEL": "none"
}
}
}
}This is the block Elastic documents for the npm package, and it is the command we ran. Put the full cluster URL in ES_URL, scheme included. OTEL_LOG_LEVEL is optional: we ran the server once without it and it still started and listed all four tools. It is in Elastic's block, so we kept it in ours. Quit and reopen Claude Desktop afterwards. [5][8]
Claude Code
One command in your terminal:
claude mcp add --env ES_URL=https://your-cluster.example:9243 --env ES_API_KEY=your_api_key --transport stdio elasticsearch -- npx -y @elastic/mcp-server-elasticsearch
Everything after the double dash is the exact command Claude Code will run. The --env flag can be repeated, which is how both variables get in, and --transport sits between the last --env and the server name because a name straight after --env is read as another pair and rejected. [9][5]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": [
"-y",
"@elastic/mcp-server-elasticsearch"
],
"env": {
"ES_URL": "<your-elasticsearch-url>",
"ES_API_KEY": "<your-api-key>"
}
}
}
}Same shape as Claude Desktop, minus the optional OTEL_LOG_LEVEL, in a different file. Cursor picks it up on restart. [10][5]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Elasticsearch
Command npx
Arguments -y @elastic/mcp-server-elasticsearch
Environment ES_URL = https://your-cluster.example:9243
ES_API_KEY = your_api_keyBoth values go in the Environment Variables field, not in Arguments. Click Test Connection first: a working server answers with its tool count, four for this one. Our run listed those same four tools with a URL that pointed at nothing, so a tool count tells you the server started, not that your cluster answered. [11]
No terminal needed
Set the Elasticsearch MCP server up without the terminal.
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines.
01
Install Routines
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Collect the cluster URL and an API key
This server needs two things before it can answer anything: the address of an Elasticsearch cluster you can reach, written in full with https:// and the port, and a credential for it. Elastic's own guidance is to create a dedicated API key rather than reuse an admin one: the cluster monitor privilege, plus read and view_index_metadata on only the indices you want an assistant to see.
03
Open the MCP settings
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
Choose Command (stdio)
Switch the form to Command (stdio): this server is a command, not a web address. Name: Elasticsearch. Command: npx. Arguments: -y @elastic/mcp-server-elasticsearch. The Arguments field splits on spaces, so those two words go in as written.
05
Add the two variables, test, then add
In Environment Variables add ES_URL with your cluster address, then ES_API_KEY with the key. Click Test Connection: Routines starts the server and reports how many tools it found, four for this one. Worth knowing from our run: those four are listed even when the URL leads nowhere, so treat a green test as proof the server started, not as proof the cluster replied. Then click Add Server.
06
Use it
The tools work in chat right away, so you can ask what indices your cluster holds without leaving the conversation. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A daily error digest
Prompt
Every weekday at 8:30, search my logs index for entries from the last 24 hours at error level, group them by message, and write the ten most frequent ones with their counts to error-digest.md.
A field map in plain English
Prompt
Every Friday at 16:00, read the field mappings for my main product index and explain in plain English which fields can be searched as free text and which only match exactly, saved as mappings-notes.md.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
Every tool call answers with a connection error
What you see
Error: connection failed (http://localhost:9201/)
The fix
This is the error our own run produced, on purpose: we pointed ES_URL at a port with nothing behind it. Note the shape, because it catches people out. The call succeeds at the protocol level and the failure arrives as ordinary tool result text, so a client watching only for JSON-RPC errors sees a normal answer. Point ES_URL at a cluster that is running and reachable from this Mac, VPN and firewall included, and ask again.
The server exits at startup and the client waits forever
What you see
Server error: [
{
"code": "too_small",
"minimum": 1,
"type": "string",
"inclusive": true,
"exact": false,
"message": "Elasticsearch URL cannot be empty",
"path": [
"url"
]
},
{
"validation": "url",
"code": "invalid_string",
"message": "Invalid Elasticsearch URL format",
"path": [
"url"
]
}
]The fix
ES_URL is missing or empty. We triggered this by starting the server with ES_URL set to an empty string: it printed this to stderr and exited, so the handshake never completed and our client sat there until it timed out. Set ES_URL to a full URL with the scheme in front, like https://your-cluster.example:9243, and check the variable is actually reaching the server rather than sitting in a shell you started it from.
A call is rejected before it ever reaches Elasticsearch
What you see
MCP error -32602: Invalid arguments for tool list_indices: [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": [
"indexPattern"
],
"message": "Required"
}
]The fix
We called list_indices with index_pattern instead of indexPattern. The parameter names are camelCase and the server validates them before it opens a connection, so nothing left the Mac. The exact names are in the tool table above: indexPattern, index and queryBody. If you see this in normal use, the assistant built a malformed call; ask the same question again in plainer words.
npm says the package is deprecated while it installs
What you see
npm warn deprecated @elastic/mcp-server-elasticsearch@0.3.1: This package is deprecated. Please see the README at https://github.com/elastic/mcp-server-elasticsearch for details on how to run v0.4.0 or later.
The fix
Nothing is wrong with your setup. Elastic marked the published package deprecated on the registry, and npx prints the notice while it downloads. We only saw it on a clean npm cache: once the package is cached on your Mac the line stops appearing, which is why a colleague may not see it at all. The server itself still starts and still lists its four tools, as our run shows. Read the FAQ above on what Elastic replaced it with before you build something long-lived on it.
Your MCP client cannot start the server at all
The fix
The npx command belongs to Node.js, and this package asks for Node 18 or newer. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
Questions people ask.
What is the Elasticsearch MCP server?
It is Elastic's own MCP server for Elasticsearch. Once connected, an AI assistant such as Claude can ask a cluster which indices exist, what fields they hold, how the shards are doing, and run a real query DSL search, all from a normal conversation. It runs as a local process on your Mac over stdio and talks to whatever address you put in ES_URL, so the data itself stays wherever your cluster already lives. [5][1]
What tools does the Elasticsearch MCP server include?
Four, and the table above is the live tools/list output, word for word: list_indices, get_mappings, search and get_shards. The search tool takes a complete Elasticsearch query DSL object, so anything you can express in that JSON is reachable, with optional profiling and explain flags. All four are read-only lookups: this server has no tool that indexes, updates or deletes a document.
Do I need my own Elasticsearch cluster and an API key?
Yes, and this is the honest limit of what we verified. With ES_URL pointing at a dead port the server still started and still listed all four tools, which is why the tool table above is real. But every one of our four calls came back with the connection error printed in the troubleshooting section, so we never saw this server read a document and we do not claim we did. To use it you need a cluster you can reach plus a credential, and Elastic recommends a dedicated API key scoped to the cluster monitor privilege with read and view_index_metadata on named indices, rather than an admin credential. [5]
Is this package still maintained?
Not in the way you would want before building on it. npm carries a deprecation notice on version 0.3.1, the same notice npx prints on a fresh install, and it is quoted above. The README on the repository main branch opens with a caution that the server is deprecated and will receive only critical security updates. Version 0.3.1 was published on 2025-07-01 and is still the newest release on npm, while the repository itself moved on: its main branch now holds a Rust project with a Dockerfile and no package.json at all. The README at that same 0.3.1 tag opens by saying the repository contains experimental features intended for research and evaluation and are not production-ready, which was true before the deprecation notice arrived. [1][6][3]
What is Elastic replacing it with?
Two things, depending on what you need. Version 0.4.0 and later of this same server ships as a container image rather than an npm package, which means Docker. Separately, Elasticsearch and Kibana now carry an MCP endpoint of their own, the Agent Builder MCP server at {KIBANA_URL}/api/agent_builder/mcp, which needs no package at all: a client connects to it over HTTP with an API key, or with OAuth on Serverless projects. The README calls that the successor and says it is available in Elastic 9.2.0 and later and in Elasticsearch Serverless projects. We tested neither path: Docker was out of scope for this run, and the Agent Builder endpoint only exists on a Kibana instance, which this Mac does not have. [6][7]
Do I need the terminal to set it up?
No. In Routines you fill four fields in Settings, two of them the cluster URL and the key, and click Test Connection; the walkthrough above shows every click. Claude Desktop needs a small JSON file edited once. Only Claude Code is terminal-first by nature. [11][8]
Which apps can use the Elasticsearch MCP server?
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs, and every one of them needs the same two environment variables. [8][9][10][11]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
npm registry: @elastic/mcp-server-elasticsearchaccessed 2026-08-03Latest version 0.3.1, published 2025-07-01, license Apache-2.0, engines node >=18, and a deprecated field carrying the notice npm prints on install. Five versions in total, from 0.1.0 in March 2025.
[2]
npm downloads API: last weekaccessed 2026-08-031,717 downloads for the week ending 2026-08-01, and 6,184 for the month ending the same day.
[3]
GitHub: elastic/mcp-server-elasticsearchaccessed 2026-08-03701 stars, 144 forks, 5 open issues and 10 open pull requests, not archived, license detected as Apache-2.0, and a push dated 2026-07-31 at access time, per the GitHub API. The same API shows the main branch tree holding Cargo.toml, Cargo.lock and a Dockerfile with no package.json.
[4]
[5]
README at tag v0.3.1, the version on npmaccessed 2026-08-03The npx config block we ran, the four-tool list, the environment variable table (ES_URL required, ES_API_KEY or ES_USERNAME and ES_PASSWORD for auth), the least-privilege API key recipe, and the line stating the features are experimental and not production-ready.
[6]
README on the main branch, after deprecationaccessed 2026-08-03The caution banner naming the Agent Builder MCP endpoint as the successor, available in Elastic 9.2.0 and later and in Serverless projects, plus container image instructions that apply to 0.4.0 and later.
[7]
Elastic docs: Agent Builder MCP serveraccessed 2026-08-03The endpoint at {KIBANA_URL}/api/agent_builder/mcp, the space-scoped variant, and the API key versus OAuth 2.1 comparison.
[8]
modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03Where claude_desktop_config.json lives and how Claude Desktop loads it.
[9]
Claude Code docs: MCPaccessed 2026-08-03The claude mcp add syntax, the repeatable --env flag and the rule that a server name must not follow it directly, and why the double dash separates Claude Code options from the server command.
[10]
[11]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors and any MCP server.
This page describes Elasticsearch as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines