Elasticsearch MCP Server

What is Elasticsearch MCP Server about?

Enables any MCP‑compatible client to interact with an Elasticsearch cluster using natural language. The server translates conversational intents into Elasticsearch operations (list indices, get mappings, search, ES|QL, shard info) and returns results in a format the client can display.

How to use Elasticsearch MCP Server?

1. Prepare an Elasticsearch cluster (version 8.x or 9.x) and obtain authentication credentials (API key or username/password).
2. Run the Docker image:
   • Stdio mode (for clients that use stdio):

     docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio
     

   • Streamable‑HTTP mode (recommended):

     docker run --rm -e ES_URL -e ES_API_KEY -p 8080:8080 docker.elastic.co/mcp/elasticsearch http
     

   • Optionally set ES_SSL_SKIP_VERIFY=true to ignore TLS verification.
3. Configure the MCP client (e.g., Claude Desktop) with the appropriate command, arguments, and environment variables as shown in the README.

Key features of Elasticsearch MCP Server

• Built‑in tools: list_indices, get_mappings, search, esql, get_shards.
• Supports both stdio and streamable‑HTTP transports (SSE deprecated).
• Works with Elasticsearch 8.x & 9.x.
• Docker‑first distribution – no host‑side dependencies beyond Docker.
• Simple environment‑variable configuration for URL, authentication, and TLS handling.

Use cases of Elasticsearch MCP Server

• Conversational data exploration: AI assistants can retrieve documents, run queries, or explore index mappings through chat.
• Rapid prototyping of AI‑driven search interfaces without writing ES DSL manually.
• Integrating Elasticsearch into LLM‑powered workflows such as code assistants, knowledge bases, or analytics dashboards.
• Testing and debugging of MCP client implementations by providing a ready‑to‑use server.

FAQ from the Elasticsearch MCP Server

• Q: Which Elasticsearch versions are supported? A: Versions 8.x and 9.x.
• Q: How is authentication handled? A: Provide either an ES_API_KEY or ES_USERNAME/ES_PASSWORD via environment variables.
• Q: Do I need to mount any certificates for TLS? A: Not yet; you can skip verification with ES_SSL_SKIP_VERIFY=true. Custom certificates are planned for a future release.
• Q: Is SSE still usable? A: Yes, but it is deprecated; streamable‑HTTP is recommended.
• Q: Can I run the server without Docker? A: Current releases are distributed exclusively as a Docker image.
• Q: How do I expose the server to a remote client? A: Map the container port (default 8080) to the host and point the client to http://<host>:8080/mcp.

Elasticsearch MCP Server

[!CAUTION]

WARNING: this MCP server is EXPERIMENTAL.

Connect to your Elasticsearch data directly from any MCP Client 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.

Available Tools

• 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
• esql: Perform an ES|QL query
• get_shards: Get shard information for all or specific indices

Prerequisites

• An Elasticsearch instance
• Elasticsearch authentication credentials (API key or username/password)
• An MCP Client (e.g. Claude Desktop, Goose)

Supported Elasticsearch versions

This works with Elasticsearch versions 8.x and 9.x.

Installation & Setup

[!NOTE]

Versions 0.3.1 and earlier were installed via npm. These versions are deprecated and no longer supported. The following instructions only apply to 0.4.0 and later.

To view instructions for versions 0.3.1 and earlier, see the README for v0.3.1.

This MCP server is provided as a Docker image at docker.elastic.co/mcp/elasticsearch that supports MCP's stdio, SSE and streamable-HTTP protocols.

Running this container without any argument will output a usage message:

docker run docker.elastic.co/mcp/elasticsearch

Usage: elasticsearch-mcp-server <COMMAND>

Commands:
  stdio  Start a stdio server
  http   Start a streamable-HTTP server with optional SSE support
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Using the stdio protocol

The MCP server needs environment variables to be set:

• ES_URL: the URL of your Elasticsearch cluster
• For authentication use either an API key or basic authentication:
  • API key: ES_API_KEY
  • Basic auth: ES_USERNAME and ES_PASSWORD
• Optionally, ES_SSL_SKIP_VERIFY set to true skips SSL/TLS certificate verification when connecting to Elasticsearch. The ability to provide a custom certificate will be added in a later version.

The MCP server is started in stdio mode with this command:

docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio

The configuration for Claude Desktop is as follows:

{
 "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>"
    }
   }
 }
}

Using the streamable-HTTP and SSE protocols

Note: streamable-HTTP is recommended, as SSE is deprecated.

The MCP server needs environment variables to be set:

• ES_URL, the URL of your Elasticsearch cluster
• For authentication use either an API key or basic authentication:
  • API key: ES_API_KEY
  • Basic auth: ES_USERNAME and ES_PASSWORD
• Optionally, ES_SSL_SKIP_VERIFY set to true skips SSL/TLS certificate verification when connecting to Elasticsearch. The ability to provide a custom certificate will be added in a later version.

The MCP server is started in http mode with this command:

docker run --rm -e ES_URL -e ES_API_KEY -p 8080:8080 docker.elastic.co/mcp/elasticsearch http

If for some reason your execution environment doesn't allow passing parameters to the container, they can be passed using the CLI_ARGS environment variable: docker run --rm -e ES_URL -e ES_API_KEY -e CLI_ARGS=http -p 8080:8080...

The streamable-HTTP endpoint is at http:<host>:8080/mcp. There's also a health check at http:<host>:8080/ping

Configuration for Claude Desktop (free edition that only supports the stdio protocol).

1. Install mcp-proxy (or an equivalent), that will bridge stdio to streamable-http. The executable will be installed in ~/.local/bin:

   uv tool install mcp-proxy
   

2. 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"
         ]
       }
     }
   }