elastic-mcp

⚠️ Disclaimer: this MCP server was vibe coded. It was built iteratively with an AI assistant and is typechecked and unit-tested, but review it yourself before relying on it — especially the write tools — and use it at your own risk.

A Model Context Protocol server for Elasticsearch, written in JavaScript with JSDoc types checked by TypeScript (@ts-check / checkJs). Read-only by default, with optional write tools.

It exposes search, index inspection, and cluster information tools over the stdio transport, and transparently supports:

• Elasticsearch deployments served behind a reverse proxy under a base path (for example https://host/elasticsearch) — something the official client does not handle out of the box.
• Both Elasticsearch 8.x and 9.x clusters — the v9 client speaks compatible-with=9 and is rejected by 8.x clusters, so the matching client major is selected at startup (auto-detected or pinned).

Tested in corporate environments where API keys are often issued to restricted users with limited privileges (e.g. index read only, without cluster monitor or view_index_metadata). The server is built to degrade gracefully in these setups rather than fail outright — it falls back to lower-privilege APIs where possible and surfaces clear authorization errors otherwise. See Elasticsearch version compatibility and the privilege fallback table for details.

Usage

Run it straight from npm with npx (no install needed — set the environment variables from Configuration first):

ELASTICSEARCH_URL=http://localhost:9200/elastic npx elastic-mcp

Or install it globally to get the elastic-mcp command on your PATH:

npm install -g elastic-mcp
ELASTICSEARCH_URL=http://localhost:9200/elastic elastic-mcp

Claude Desktop / Claude Code

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "elastic": {
      "command": "npx",
      "args": ["-y", "elastic-mcp"],
      "env": {
        "ELASTICSEARCH_URL": "https://host/elasticsearch",
        "ELASTICSEARCH_API_KEY": "<base64-api-key>"
      }
    }
  }
}

Tools

Read tools

Always registered, and all marked read-only (readOnlyHint).

| Tool | Description | | --- | --- | | search | Run a Query DSL search (query, aggs, sort, size, from, _source). | | count | Count documents matching an optional query. | | esql | Run an ES|QL query (complete query string); returns column metadata plus keyed row objects. Requires Elasticsearch 8.11+. | | get_document | Fetch a single document by index and id. | | list_indices | List indices with health, status, doc count, and size; falls back to names-only via _resolve/index without cluster monitor. | | get_mapping | Get field mappings for one or more indices; falls back to read-level _field_caps (field names + types) without view_index_metadata. | | get_settings | Get settings for one or more indices. | | get_aliases | List index aliases. | | list_shards | List shards with role, state, doc count, store size, and node (equivalent to _cat/shards); the doc count and store size come back null without cluster monitor. | | get_kibana_object | Fetch a Kibana saved object by <type>:<id>; decodes inline JSON-string fields (visState, searchSourceJSON, ...) and resolves references[] to titles. Reads .kibana_analytics / .kibana, so the key needs read on those. | | cluster_health | Cluster health, optionally scoped to indices. | | cluster_stats | Cluster-wide statistics. | | cluster_info | Cluster name, UUID, and version. | | list_nodes | List nodes with role, heap, CPU, and load. |

Write tools

Off by default. Registered only when ELASTICSEARCH_ENABLE_WRITES=true. Each is marked destructiveHint (except create_index) so MCP clients can prompt for confirmation, and of course only works if the API key carries the matching write privileges.

| Tool | Description | | --- | --- | | index_document | Create or replace a document (auto-generates an id if omitted; createOnly to avoid overwriting). | | update_document | Partially update a document by id, with optional upsert. | | delete_document | Delete a single document by id. | | create_index | Create an index, optionally with mappings, settings, and aliases. | | delete_index | Permanently delete one or more indices — cannot be undone. |

Configuration

Configuration is read from environment variables (see .env.example):

| Variable | Required | Description | | --- | --- | --- | | ELASTICSEARCH_URL | yes | Endpoint URL, optionally including a base path. | | ELASTICSEARCH_API_KEY | no | Base64 API key; takes precedence over basic auth. | | ELASTICSEARCH_USERNAME | no | Basic-auth username. | | ELASTICSEARCH_PASSWORD | no | Basic-auth password. | | ELASTICSEARCH_CA_FINGERPRINT | no | SHA-256 fingerprint of the CA certificate. | | ELASTICSEARCH_TLS_VERIFY | no | Defaults to true; set to false to accept self-signed/invalid certs (dev only). | | ELASTICSEARCH_API_VERSION | no | 8, 9, or auto (default). Selects the client major; see below. | | ELASTICSEARCH_ENABLE_WRITES | no | Set to true to register the write tools. Off by default (server is read-only). |

Elasticsearch version compatibility

The official client always sends a compatible-with=<major> media type that matches its own major version, and a cluster of a different major rejects it. To work against both 8.x and 9.x clusters, both client majors are bundled and the right one is chosen at startup:

• auto (default) — probe the cluster's root endpoint (with a plain application/json request that side-steps the compatibility header) and pick the matching client major. Anything up to 8.x uses the v8 client; 9.x and newer use the v9 client.
• 8 / 9 — pin the client major explicitly and skip the probe.

Note: the root probe requires the cluster:monitor/main privilege. Index-scoped API keys often lack it (it can only be granted by an admin), in which case the probe fails with action [cluster:monitor/main] is unauthorized. When that happens the server logs a warning and falls back to the v8 client, which speaks compatible-with=8 — accepted by both 8.x and 9.x clusters — so search and index inspection keep working. Set ELASTICSEARCH_API_VERSION explicitly to skip the probe (and the warning) entirely.

Base path support

When ELASTICSEARCH_URL contains a path (e.g. https://host/elasticsearch), the URL is split into its origin (https://host) and prefix (/elasticsearch). A custom connection class prepends the prefix to every request path, because the official client routes requests against the origin only and silently drops the path.

Creating an API key

By default the server is read-only, so it only needs cluster monitor rights (for cluster_health, cluster_stats, cluster_info, list_nodes, and the _cat listings) plus read and view_index_metadata on the indices you want to expose. Create a least-privilege key with the Create API key API:

POST /_security/api_key
{
  "name": "elastic-mcp",
  "role_descriptors": {
    "elastic_mcp_read_only": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}

Or with curl:

curl -u elastic -X POST "$ELASTICSEARCH_URL/_security/api_key" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "elastic-mcp",
    "role_descriptors": {
      "elastic_mcp_read_only": {
        "cluster": ["monitor"],
        "indices": [
          { "names": ["*"], "privileges": ["read", "view_index_metadata"] }
        ]
      }
    }
  }'

The response contains an encoded field — that base64 value is exactly what ELASTICSEARCH_API_KEY expects:

{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "elastic-mcp",
  "api_key": "ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

ELASTICSEARCH_API_KEY=VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==

Restrict indices[].names to specific index names or patterns to narrow access further.

Kibana saved-object access (only for get_kibana_object)

get_kibana_object reads Kibana's saved objects straight from the .kibana_analytics and .kibana indices. These are restricted system indices, so a plain read on * does not reach them — the role needs a dedicated entry that opts in with allow_restricted_indices. Add it alongside the existing read entry (keep the wildcard entry at false so the key cannot read other system indices such as .security-*):

{
  "name": "elastic-mcp",
  "role_descriptors": {
    "elastic_mcp_read_only": {
      "cluster": ["monitor"],
      "indices": [
        { "names": ["*"], "privileges": ["read", "view_index_metadata"], "allow_restricted_indices": false },
        { "names": [".kibana*"], "privileges": ["read"], "allow_restricted_indices": true }
      ]
    }
  }
}

To widen an existing key without rotating it, the Update API key API (PUT /_security/api_key/<id>) rewrites its role_descriptors in place — the id and encoded value are unchanged, so ELASTICSEARCH_API_KEY does not need updating. Omit this entry entirely if you do not use get_kibana_object; the tool then returns an authorization error and the rest of the server is unaffected.

Write privileges (only if ELASTICSEARCH_ENABLE_WRITES=true)

The read-only key above cannot mutate data — the write tools would return authorization errors. To allow them, add the relevant index privileges: write (covers index_document, update_document, delete_document), create_index, and delete_index:

{
  "name": "elastic-mcp",
  "role_descriptors": {
    "elastic_mcp_read_write": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["*"],
          "privileges": ["read", "view_index_metadata", "write", "create_index", "delete_index"]
        }
      ]
    }
  }
}

Grant only the subset you need — for example drop delete_index if you never delete indices. Cluster monitor remains optional (see the fallback table below).

Graceful privilege degradation

Some tools degrade gracefully when privileges are missing, falling back once to a lower-privilege API and remembering that for the rest of the process so they don't retry the rejected endpoint:

| Tool | Needs | Fallback when missing | Granted by | | --- | --- | --- | --- | | list_indices | cluster monitor | _resolve/index (names only) | view_index_metadata | | get_mapping | view_index_metadata | _field_caps (field names + types) | read |

So a key with only read + view_index_metadata (or even just read) still gets useful results from search, count, esql, get_document, get_mapping, and list_indices. The tools that have no lower-privilege equivalent — cluster_health, cluster_stats, cluster_info, list_nodes (cluster monitor), get_settings, get_aliases (view_index_metadata), and get_kibana_object (restricted .kibana* read, see above) — return an authorization error without the privilege.

Contributing

See CLAUDE.md for the project layout, architecture notes, and coding conventions.

License

ISC — see LICENSE.