Elasticsearch MCP Server: Search Your Cluster with AI

⏱️ 3 min read 🔌 MCP Server

What it is: Elastic's own MCP server, @elastic/mcp-server-elasticsearch, which exposes index listing, mapping inspection, and query execution against an Elasticsearch (or Elastic Cloud) deployment. It talks to the standard Elasticsearch REST API, so it works against self-hosted clusters and Elastic Cloud alike.

Quick answer: Run npx -y @elastic/mcp-server-elasticsearch with your cluster URL and an API key set as environment variables, and the agent can list indices, read mappings, and run search queries. Use an API key scoped to specific indices with only read privileges rather than a superuser credential.

Why it matters for data work

Elasticsearch's query DSL is powerful but verbose, and most people who need an answer from it don't want to hand-write a bool query with nested filters. Through MCP, the agent can inspect an index's mapping to know what fields exist and their types, then construct the query itself — turning "which orders had a shipping error last week" into a real search instead of a support ticket to whoever remembers the schema.

Install & configure

Authentication is via API key (recommended) or basic auth, passed as environment variables:

# Claude Code
claude mcp add elasticsearch -e ES_URL=https://my-cluster.es.io:443 \
  -e ES_API_KEY=<api-key> -- npx -y @elastic/mcp-server-elasticsearch

// Claude Desktop / Cursor config
{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@elastic/mcp-server-elasticsearch"],
      "env": {
        "ES_URL": "https://my-cluster.es.io:443",
        "ES_API_KEY": "<api-key>"
      }
    }
  }
}

Generate the API key from Kibana (Stack Management → API Keys) or the _security/api_key endpoint rather than reusing a personal login — check the repo's README for the exact current variable names, since Elastic has iterated on auth options (basic-auth env vars are also supported for self-hosted clusters without API keys enabled).

Point it at one index or the whole cluster?

By default the server can see every index the API key's role grants, which on a shared cluster likely means far more than the task in front of you. Elasticsearch's role-based access control lets you scope a key to named indices or an index pattern (logs-app-*) with only the privileges it needs (read, view_index_metadata) — create that narrower role before wiring the server into a client, rather than starting from a cluster-admin key and meaning to lock it down later.

How do I keep it safe?

The server can execute arbitrary queries against whatever the API key can reach, so the key's role is your real access-control boundary, not the MCP layer. Grant read-only privileges for exploratory work, avoid manage or write unless the agent genuinely needs to index or update documents, and rotate API keys the same way you would any other service credential. If a cluster holds customer PII, consider field-level or document-level security on the role so search results themselves are redacted before the agent ever sees them.

Troubleshooting

Common failure points when wiring this up:

401/403 errors: the API key's role doesn't have the privilege the query needs — check the role's index privileges, not just cluster-level ones.
Connection/SSL errors: self-signed certs on a self-hosted cluster need the CA trusted in the environment running the server, or a documented flag to relax verification for local dev only.
Agent can't find an index it should see: confirm the index isn't hidden (a leading dot) or excluded by the key's index pattern.
Tools don't appear after config edit: Claude Desktop and Cursor only read MCP config at launch — fully restart the app.

Author & links

Author: Elastic (official)

Repo: github.com/elastic/mcp-server-elasticsearch

License: Apache-2.0

Related skills

For a key-value/cache store, see the Redis MCP server. For a document database with a similar JSON-first feel, see the MongoDB MCP server. For SQL-first warehouse search, see the ClickHouse MCP server.

← Back to MCP Servers