mcp-server-elasticsearch

Elasticsearch MCP Server

[!CAUTION] This MCP server is deprecated and will only receive critical security updates going forward. It has been superseded by the Elastic Agent Builder MCP endpoint, which is available in Elastic 9.2.0+ and Elasticsearch Serverless projects.

Use the Elasticsearch MCP Server for AI Agents

The Elasticsearch MCP Server connects your AI agents to Elasticsearch data using the Model Context Protocol (MCP). It enables natural language interactions with your Elasticsearch indices, allowing agents to query, analyze, and retrieve data without custom APIs.

Follow these steps to deploy and configure the Elasticsearch MCP Server container image from AWS Marketplace.

Before you begin

Before you start, ensure you have:

• An Elasticsearch cluster (version 8.x or 9.x) accessible from your AWS environment
• Elasticsearch authentication credentials:
  • An API key, or
  • A username and password pair
• Docker installed and running in your AWS environment (for example, on an EC2 instance or in a container service)
• An MCP client configured (such as Claude Desktop, Cursor, VS Code, or another MCP-compatible tool)
• Network connectivity between your deployment environment and your Elasticsearch cluster

[!NOTE]

These instructions apply to Elasticsearch MCP Server 0.4.0 and later. For versions 0.3.1 and earlier, refer to the README for v0.3.1.

Deploy the Elasticsearch MCP Server

The Elasticsearch MCP Server is provided as a Docker container image available from AWS Marketplace. You can run it using either the stdio protocol (for direct client connections) or the streamable-HTTP protocol (for web-based integrations).

Choose a protocol

The server supports two protocols:

• stdio: Direct communication between the MCP client and server. Use this when your client supports stdio and runs in the same environment.
• streamable-HTTP: HTTP-based protocol recommended for web integrations, stateful sessions, and concurrent clients.

Note: Server-Sent Events (SSE) is deprecated. Use streamable-HTTP instead.

Configure the stdio protocol

Use the stdio protocol when your MCP client connects directly to the server process.

Set environment variables for stdio mode

Set the following environment variables:

• ES_URL: The URL of your Elasticsearch cluster (for example, https://your-cluster.es.amazonaws.com:9200)
• For authentication, use one of these options:
  • API key: Set ES_API_KEY to your Elasticsearch API key
  • Basic authentication: Set ES_USERNAME and ES_PASSWORD to your Elasticsearch credentials
• (Optional) ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification when connecting to Elasticsearch. Only use this for development or testing environments.

Run the container in stdio mode

Start the MCP server in stdio mode:

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

Configure Claude Desktop

Add this configuration to your Claude Desktop configuration file:

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

Replace <elasticsearch-cluster-url> with your Elasticsearch cluster URL and <elasticsearch-API-key> with your API key.

Configure the streamable-HTTP protocol

Use the streamable-HTTP protocol for web-based integrations or when you need to support multiple concurrent clients.

Set environment variables for HTTP mode

Set the same environment variables as the stdio protocol:

• ES_URL: The URL of your Elasticsearch cluster
• For authentication, use one of these options:
  • API key: Set ES_API_KEY to your Elasticsearch API key
  • Basic authentication: Set ES_USERNAME and ES_PASSWORD to your Elasticsearch credentials
• (Optional) ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification

Run the container in HTTP mode

Start the MCP server in HTTP mode:

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

The streamable-HTTP endpoint is available at http://<host>:8080/mcp. A health check endpoint is available at http://<host>:8080/ping.

Configure Claude Desktop with HTTP proxy

If you're using Claude Desktop (free edition) which only supports the stdio protocol, use mcp-proxy to bridge stdio to streamable-HTTP:

1. Install mcp-proxy:

   uv tool install mcp-proxy
   

   For alternative installation options, refer to mcp-proxy/README.md.

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

   Replace <home-directory>, <elasticsearch-API-key>, <mcp-server-host>, and <mcp-server-port> with your values.

Verify the connection

After configuring your MCP client, verify the connection works:

1. Start your MCP client (for example, Claude Desktop or Cursor).
2. Check that the Elasticsearch MCP Server appears in your available MCP servers.
3. Test a simple query through your agent interface to confirm it can access your Elasticsearch indices.

If the connection fails, verify:

• Your Elasticsearch cluster URL is correct and accessible from your AWS environment
• Your authentication credentials are valid and have the necessary permissions
• Network connectivity exists between the container and your Elasticsearch cluster (check security groups and network ACLs)
• Docker is running and the container started successfully (check container logs with docker logs <container-id>)

Monitor health and status

Monitor the health and proper function of the Elasticsearch MCP Server using these methods:

Check container status

Verify the container is running:

docker ps | grep elasticsearch-mcp-server

The container should appear in the list with a status of Up.

Test the health endpoint (HTTP mode)

If you're using the streamable-HTTP protocol, test the health check endpoint:

curl http://<host>:8080/ping

A successful response returns pong, indicating the server is running and healthy.

Check container logs

View container logs to identify any issues:

docker logs <container-id>

Look for error messages related to:

• Elasticsearch connection failures
• Authentication errors
• Network connectivity issues

Verify Elasticsearch connectivity

Test connectivity to your Elasticsearch cluster from the container:

docker exec <container-id> curl -k -u <username>:<password> <ES_URL>

Or with an API key:

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

A successful response indicates the container can reach your Elasticsearch cluster.

Security and sensitive information

The Elasticsearch MCP Server handles authentication credentials securely:

Credential storage

• API keys and passwords: Stored only in environment variables passed to the container. They are not persisted to disk or logged.
• Environment variables: Set when you run the container. Use AWS Secrets Manager or AWS Systems Manager Parameter Store to manage credentials securely in production environments.

Data encryption

• In transit: The MCP server communicates with Elasticsearch over HTTPS when your ES_URL uses the https:// protocol. Ensure your Elasticsearch cluster has SSL/TLS enabled.
• At rest: The container does not store data locally. All data remains in your Elasticsearch cluster, which uses your cluster's encryption settings.

Best practices

• Rotate API keys regularly (every 30-90 days for production environments)
• Use API keys with minimal required permissions (read-only access to specific indices when possible)
• Never commit credentials to version control or share them in logs
• Use AWS Secrets Manager or Parameter Store to inject credentials at runtime instead of hardcoding them

AWS service quotas

The Elasticsearch MCP Server runs as a container in your AWS environment. Consider these AWS service quotas:

• EC2 instance limits: If running on EC2, ensure your instance type supports your expected workload
• Elastic Container Service (ECS): If using ECS, review ECS service quotas
• Elastic Kubernetes Service (EKS): If using EKS, review EKS service quotas
• Network bandwidth: Ensure sufficient network bandwidth between your container and Elasticsearch cluster

To request quota increases, use the AWS Service Quotas console or refer to the AWS General Reference Guide.

Available tools

Once connected, the MCP server provides these tools to your agent:

• list_indices: List all available Elasticsearch indices
• get_mappings: Get field mappings for a specific Elasticsearch index
• search: Perform an Elasticsearch search using query DSL
• esql: Execute an ES|QL query
• get_shards: Get shard information for all or specific indices

Your agent can use these tools to interact with your Elasticsearch data through natural language conversations.

Next steps

• Learn about AI-powered features available in the Elastic platform
• Explore Agent Builder for building custom AI agents with Elasticsearch