mcp -elasticsearch

This MCP server provides a bridge between MCP clients and an Elasticsearch data store. It exposes a set of Elasticsearch-oriented tools via MCP, including listing indices, retrieving field mappings, performing DSL searches, executing ES|QL queries, and retrieving shard information. You connect to the server from your MCP client (for example Claude Desktop or similar MCP-enabled clients) using the stdio transport (or HTTP/streamable-http via a proxy) and then issue tool commands such as list_indices or get_mappings to interact with your Elasticsearch data through natural language conversations. The server expects you to supply Elasticsearch connection details through environment variables or client-side configuration, typically including the cluster URL and authentication credentials (API key or username/password).

Typical workflow:

• Start the MCP server container with the required ES_URL and credentials.
• In your MCP client, invoke tools like list_indices to see available indices, get_mappings to inspect a specific index, and search to run a DSL-based query. You can also use esql for ES|QL queries and get_shards to learn about shard distribution.
• If you’re using the stdio protocol, ensure your client is wired to the server’s standard input/output; for streamable-http, connect via the HTTP endpoint documented in the README.

Prerequisites:

• Docker installed and running on your host
• Access to an Elasticsearch cluster (8.x or 9.x) with credentials (API key or username/password)
• An MCP client that supports Model Context Protocol (e.g., Claude Desktop)

Installation steps:

1. Run the MCP server container (stdio protocol) using environment variables for Elasticsearch:

# Example: start the stdio MCP server container
docker run -i --rm \
  -e ES_URL="<elasticsearch-cluster-url>" \
  -e ES_API_KEY="<elasticsearch-API-key>" \
  docker.elastic.co/mcp/elasticsearch \
  stdio

2. For clients that require a configuration file, use the following example to connect Claude Desktop (or compatible MCP client) to the stdio-based MCP server:

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

3. If you prefer using the streamable-http protocol instead of stdio, follow the HTTP/CLI proxy guidance in the README and ensure your client is configured to bridge stdio to streamable-http as needed.

Notes and tips:

• This MCP server is deprecated and primarily maintained for critical security updates; consider migrating to Elastic Agent Builder's MCP endpoint if possible (Elastic 9.2.0+).
• Supported Elasticsearch versions are 8.x and 9.x.
• When using HTTP or streamable-http, ensure ES_SSL_SKIP_VERIFY is considered if you’re using self-signed certificates (the server supports skipping verification if needed).
• If using API key authentication, pass ES_API_KEY; for basic auth, you can use ES_USERNAME and ES_PASSWORD.
• The available MCP tools are: list_indices, get_mappings, search, esql, and get_shards. Each tool maps to a typical Elasticsearch operation (index enumeration, mapping retrieval, DSL search, ES|QL query, and shard details respectively).
• If you’re running in environments that don’t allow direct container arguments, you can supply CLI_ARGS to customize the server startup (for example, to enable http mode and port mappings).