# Elasticsearch > Search indices, inspect mappings, and run queries against Elasticsearch from an AI agent. [Canonical HTML page](https://top-mcps.com/mcp/elasticsearch) · [server.json](https://top-mcps.com/mcp/elasticsearch.json) · [methodology](https://top-mcps.com/about/methodology) ## Install ### Claude Desktop — `claude_desktop_config.json` Paste under mcpServers. Fully quit and reopen Claude after editing. ```json { "mcpServers": { "elasticsearch": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### Claude Code — `CLI or .mcp.json` Run from your repo. Commit .mcp.json to share with your team. ```shell # export ES_URL=https://my-cluster.es.eastus2.azure.elastic-cloud.com:9243 # export ES_API_KEY=changeme claude mcp add elasticsearch -- docker run --rm -i -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/server-elasticsearch:latest ``` ### Cursor — `.cursor/mcp.json` Global path: ~/.cursor/mcp.json. Reload window after editing. ```json { "mcpServers": { "elasticsearch": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### VS Code — `.vscode/mcp.json` VS Code uses the "servers" key (not "mcpServers"). ```jsonc { "servers": { "elasticsearch": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### Windsurf — `~/.codeium/windsurf/mcp_config.json` Open via Cascade → hammer icon → Configure. ```json { "mcpServers": { "elasticsearch": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### Cline — `cline_mcp_settings.json` Open via the Cline sidebar → MCP Servers → Edit. ```json { "mcpServers": { "elasticsearch": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### Continue — `~/.continue/config.json` Continue uses modelContextProtocolServers with a transport block. ```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ], "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } ] } } ``` ### Codex CLI — `~/.codex/config.toml` Codex uses TOML. Each server is a [mcp_servers.] subtable. ```shell # ~/.codex/config.toml [mcp_servers.elasticsearch] command = "docker" args = [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest", ] env = { ES_URL = "${ES_URL}", ES_API_KEY = "${ES_API_KEY}" } ``` ### Zed — `~/.config/zed/settings.json` Zed calls them "context_servers". Settings live-reload on save. ```jsonc { "context_servers": { "elasticsearch": { "command": { "path": "docker", "args": [ "run", "--rm", "-i", "-e", "ES_URL", "-e", "ES_API_KEY", "docker.elastic.co/mcp/server-elasticsearch:latest" ] }, "env": { "ES_URL": "${ES_URL}", "ES_API_KEY": "${ES_API_KEY}" } } } } ``` ### ChatGPT — `ChatGPT → Apps directory` Elasticsearch doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build. ```none ``` ## At a glance - **Maintainer:** Elastic - **Transport:** stdio - **Auth model:** API key - **Required secrets:** ES_URL, ES_API_KEY - **Supported clients:** Claude, Cursor, VS Code, Windsurf, Any MCP-compatible client, Elasticsearch 8+, Elastic Cloud - **License:** Apache-2.0 - **Language:** TypeScript - **Latest version:** latest - **Last verified:** 2026-06-02 - **GitHub stars:** 667 (fetched 2026-06-02T13:16:41.104Z) - **Score:** 85/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology) - **Source:** https://github.com/elastic/mcp-server-elasticsearch ## Tools & permissions | Tool | Description | Args | Side effects | |------|-------------|------|--------------| | `list_indices` | List indices and aliases visible to the API key. | `—` | read | | `get_mapping` | Return field mappings for an index or alias. | `index: string` | read | | `search` | Execute a Query DSL search. | `index: string, query: object` | read | | `esql` | Execute an ES\|QL query (Elasticsearch 8.11+). | `query: string` | read | ## Security & scope - **Access scope:** read-only - **Sandbox:** Authenticates with an Elastic API key. Read-only at the tool layer; pair with an API key scoped to a single index pattern for defence in depth. - **Gotchas:** - API keys carry whatever privileges they were created with — always create a read-only key scoped to one index pattern. - Search payloads can be unbounded; cap `size` in the agent prompt for high-cardinality indices. - Elastic Cloud rate-limits aggressive queries — wide aggregations on cold tiers can take minutes. ## Quick answer **What it does.** Connects to an Elasticsearch cluster and exposes index enumeration, mapping introspection, and Query DSL search execution to AI models. Read-only. **Best for:** - Query DSL drafting - Mapping inspection - Log search and debugging - Index template audits - Alias and ILM verification **Not for:** - Index writes from an LLM - Cluster administration (use the Elastic CLI) - Cross-cluster search setup ## Description The official Elasticsearch MCP connects an AI agent to an Elasticsearch or Elastic Cloud cluster. Lists indices, returns mappings and aliases, and executes Query DSL searches against a scoped index pattern. Designed for the "what is in this index" and "why did this query return nothing" debug loops where a developer would otherwise drop into Kibana. ## Why it matters Elasticsearch is the default search and log-analytics backend for most teams. An MCP makes it possible for an AI agent to investigate logs, draft Query DSL, and validate mappings without leaving the conversation — replacing the round trip through Kibana for the common debug cases. ## Key features - Official Elastic maintainership - Index, alias, and mapping introspection - Query DSL and ES|QL execution - Read-only by default - API-key auth (no superuser tokens) ## FAQ ### API key or username/password? API key only. Create a dedicated, read-only API key in Elastic and pass it via ES_API_KEY — username/password auth is intentionally not supported because static cluster credentials are too broad for an MCP role. ### Does it support ES|QL? Yes — for Elasticsearch 8.11+ the esql tool runs a `query` against the ES|QL endpoint. Use it for tabular analytics; reach for the search tool when you need scoring or aggregations. ### Can it write or delete documents? No. The MCP exposes only search and metadata tools; index, update, delete, and reindex APIs are deliberately not surfaced. ### Does it work with OpenSearch? Partially. The search and mapping tools work for OpenSearch 2.x with compatibility mode, but ES|QL and some 8.x-only features do not. Run the official OpenSearch MCP when your cluster is OpenSearch. ## Changelog - **2026-06-02** — Refreshed install snippets and fact sheet; verified for 2026. - **2025-04-08** — Initial directory listing.