Elasticsearch MCP Server

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

Required Environment Variables:

• ES_URL: The URL of your Elasticsearch cluster.
• Authentication (choose one):
  • ES_API_KEY: Your Elasticsearch API key.
  • ES_USERNAME and ES_PASSWORD: Your Elasticsearch credentials.
• Optional:
  • ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification.

Run via Docker:

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

Endpoints:

• MCP endpoint: http://<host>:8080/mcp
• Health check: http://<host>:8080/ping (returns pong if healthy).

Claude Desktop with HTTP proxy: If your client only supports stdio (like the free edition of Claude Desktop), use mcp-proxy to bridge the connection:

1. Install mcp-proxy:

uv tool install mcp-proxy

2. Add this to Claude Desktop configuration:

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

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

Required Environment Variables:

• ES_URL: The URL of your Elasticsearch cluster (e.g., https://your-cluster.es.amazonaws.com:9200).
• Authentication (choose one):
  • ES_API_KEY: Your Elasticsearch API key.
  • ES_USERNAME and ES_PASSWORD: Your Elasticsearch credentials.
• Optional:
  • ES_SSL_SKIP_VERIFY: Set to true to skip SSL/TLS certificate verification (use only for development/testing).

Run via Docker:

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

Claude Desktop Configuration: Add the following 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>"
      }
    }
  }
}

The Elasticsearch MCP Server supports injecting environment variables into configuration files using a specific interpolation syntax. This allows you to keep sensitive information or environment-specific settings out of your static configuration files.

Syntax

You can use the following patterns within your configuration strings:

1. Standard Variable: ${VARIABLE_NAME}

   • Replaces the placeholder with the value of the environment variable VARIABLE_NAME.
   • If the variable is not defined in the environment, the interpolation will fail with an error.

2. Variable with Default Value: ${VARIABLE_NAME:default_value}

   • Replaces the placeholder with the value of VARIABLE_NAME if it exists.
   • If VARIABLE_NAME is not defined, it falls back to default_value.

Error Handling

If an interpolation fails (e.g., a variable is missing and no default is provided, or braces are mismatched), the server will report an InterpolationError specifying the reason, the line number, and the character position where the error occurred.

# Examples of interpolation syntax

# Uses the value of the ES_URL environment variable
url: "${ES_URL}"

# Uses the value of ES_URL, or falls back to localhost if not set
url: "${ES_URL:http://localhost:9200}"

You can extend the server's capabilities by defining CustomTool objects within the tools configuration. This allows AI agents to execute specific ES|QL queries or predefined Search Templates.

Custom Tool Types

• esql: Executes an ES|QL query.
  • Requires a query string.
  • Supports format options: json (default) or value.
• search_template: Executes a predefined Elasticsearch Search Template.
  • Can be identified by a template_id (string) or a full template (JSON object).

Both types inherit a base configuration containing a description, parameters (JSON schema), and optional annotations.

{
  "tools": {
    "custom": {
      "my_esql_tool": {
        "type": "esql",
        "base": {
          "description": "Runs a specific analytics query",
          "parameters": {}
        },
        "query": "FROM logs | STATS count() BY host",
        "format": "json"
      },
      "my_template_tool": {
        "type": "search_template",
        "base": {
          "description": "Uses the standard search template",
          "parameters": {}
        },
        "template": {
          "template_id": "my-template-id"
        }
      }
    }
  }
}

The server is configured using a JSON5 format (which supports comments and multiline strings, useful for ES|QL queries). Configuration can be provided via a file path or by using environment variables with a built-in default template.

Default Configuration Template

If no configuration file is provided, the server uses the following template, which interpolates environment variables:

{
    "elasticsearch": {
        "url": "${ES_URL}",
        "api_key": "${ES_API_KEY:}",
        "username": "${ES_USERNAME:}",
        "password": "${ES_PASSWORD:}",
        "ssl_skip_verify": "${ES_SSL_SKIP_VERIFY:false}"
    }
}

Configuration Keys

• elasticsearch.url: The URL of the Elasticsearch instance.
• elasticsearch.api_key: The API key for authentication.
• elasticsearch.username: The username for authentication.
• elasticsearch.password: The password for authentication.
• elasticsearch.ssl_skip_verify: Boolean flag to skip SSL verification (defaults to false).

{
    "elasticsearch": {
        "url": "https://your-es-cluster:9243",
        "api_key": "your-api-key",
        "ssl_skip_verify": false
    }
}