How to add Elasticsearch MCP Server to Windsurf

Official Elastic server: list indices, read mappings, and search with Query DSL. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 700★ · stdio · apikey · official

Windsurf config for Elasticsearch MCP Server

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

{
  "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": "<your-elasticsearch-cluster-url>",
        "ES_API_KEY": "<your-elasticsearch-api-key>"
      }
    }
  }
}

Requires Docker to be installed and running.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Elasticsearch MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Elasticsearch MCP Server's tools become available to Cascade.

Before you start

An Elasticsearch cluster, version 8.x or 9.x (self-managed, Elastic Cloud, or serverless)
An Elasticsearch endpoint URL set as ES_URL
An API key (create one in Kibana under Stack Management > Security > API keys, or via the _security/api_key API) set as ES_API_KEY — or ES_USERNAME / ES_PASSWORD basic-auth credentials
Node.js (the npm package @elastic/mcp-server-elasticsearch) or Docker installed and running to launch the container

What Elasticsearch MCP Server can do in Windsurf

list_indices

List the available indices in the Elasticsearch cluster.

get_mappings

Retrieve the field mappings for a specific index.

search

Run a search using Elasticsearch Query DSL.

esql

Execute an ES|QL query against the cluster.

get_shards

Get shard allocation and status information for indices.

Security

Use an Elasticsearch API key scoped to read-only on only the indices the agent needs rather than cluster-admin credentials. The project is deprecated to security-only maintenance, so plan to migrate to Elastic Agent Builder for new work.

Elasticsearch MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Elasticsearch MCP Server config there under the "mcpServers" key and restart the client.

Is Elasticsearch MCP Server safe to use with Windsurf?

Is this server still maintained?

It is deprecated and receives only critical security updates. Elastic recommends the Agent Builder MCP endpoint (Elastic 9.2.0+ and serverless) for new work, but the server still functions for existing and older clusters.

How do I authenticate?

Use an Elasticsearch API key set as ES_API_KEY, or basic auth with ES_USERNAME and ES_PASSWORD, alongside your ES_URL endpoint.

Which Elasticsearch versions are supported?

Elasticsearch 8.x and 9.x clusters, whether self-managed, on Elastic Cloud, or serverless.

View repo Full Elasticsearch MCP Server page