elasticsearch-mcp

MCP server for Elasticsearch, built directly on the REST API (no elasticsearch-py dependency, so it also works against OpenSearch and managed clusters that only expose HTTP).

Any MCP agent — Claude, Cursor, a custom LLM agent — can query, diagnose, map, ingest, and run gated write operations. 34 tools. Read-only by default; every write path is gated.

Live demo: an agent lists indices, reads the mapping, runs a query and SQL, and gets blocked when it tries an unsafe write. See demo/demo.py.

Install

git clone https://github.com/baburajr/elasticsearch_mcp.git && cd elasticsearch_mcp
uv sync            # or: pip install -e ".[dev]"
cp .env.example .env
pytest -q

Register with Claude Code / Claude Desktop

{
  "mcpServers": {
    "elasticsearch": {
      "command": "uv",
      "args": ["--directory", "/abs/path/elasticsearch-mcp", "run", "elasticsearch-mcp"],
      "env": {
        "ES_MCP_HOSTS": "https://es.internal:9200",
        "ES_MCP_API_KEY": "base64-encoded-api-key",
        "ES_MCP_INDEX_ALLOW": "logs-*,metrics-*",
        "ES_MCP_READ_ONLY": "true"
      }
    }
  }
}

Remote / shared deployment instead of stdio:

elasticsearch-mcp --transport streamable-http

Tools

34 tools. Write tools (marked ✎) need ES_MCP_READ_ONLY=false and confirm=true in the call. Destructive ones (marked ⚠) additionally need ES_MCP_ALLOW_DESTRUCTIVE=true.

Query

Tool	What it does
run_query	Execute Query DSL. Size capped, timeout injected, deep paging rejected, search_after supported
generate_dsl	Structured spec to valid DSL, validated against the index, returns a field catalog
explain_query	_validate?rewrite=true + profile timing breakdown + per-document _explain
count_documents	Match count without fetching hits

SQL

Tool	What it does
sql_query	Run Elasticsearch SQL via _sql (SELECT only); the FROM target is checked against the index policy. Returns columns, rows, and a paging cursor
sql_translate	Translate an SQL SELECT into native Query DSL via _sql/translate, without running it

Paging (point-in-time)

Tool	What it does
open_pit / close_pit	Open/close a point-in-time to page a large result set consistently
paged_search	Page past the 10000 deep-paging limit using the PIT + search_after, with an automatic _shard_doc tiebreak

Diagnostics

Tool	What it does
cluster_health	Status, shard counts, pending tasks, optional per-node heap/disk/CPU/rejections
index_health	Per index: docs, store, segments, avg query and index latency, merges
shard_allocation	_cat/shards plus _cluster/allocation/explain decider reasons for unassigned shards
find_slow_queries	Indices ranked by avg query latency, running search tasks, thread-pool rejections, slowlog thresholds
cat_nodes	Nodes with role, version, heap/RAM/CPU/load, and master flag
field_caps	Field types across indices via _field_caps; flags fields mapped as different types in different indices

Mapping

Tool	What it does
list_indices	Indices and aliases with doc counts and size
get_mapping	Flattened field path -> type catalog including multi-fields
analyze_text	Token output of an analyzer, for debugging zero-hit match queries
put_mapping ✎⚠	Additive mapping changes

Ingest

Tool	What it does
index_document ✎	Index a single document (create or overwrite)
bulk_index ✎	Bulk index many documents in one _bulk request, with error summary

Operations

Tool	What it does
list_snapshot_repositories, list_snapshots, snapshot_status	Snapshot inventory and progress
create_snapshot ✎	Snapshot selected indices, async by default
restore_snapshot ✎⚠	Restore, with pre-flight check for existing open indices and rename support
reindex ✎⚠	Async reindex with query, pipeline, script, slicing, throttling; returns a task id
delete_by_query ✎⚠	Delete matching docs (match_all refused); async, returns a task id
update_by_query ✎⚠	Painless script update of matching docs (match_all refused); async, returns a task id
update_settings ✎⚠	Update dynamic index settings; static settings refused
alias_actions ✎	Atomic alias add/remove, for zero-downtime reindex cutover
get_task, cancel_task	Poll or kill long-running tasks
cluster_info	Version, distribution, and the active safety policy

Configuration

All variables use the ES_MCP_ prefix, read from the environment or .env.

Variable	Default	Purpose
HOSTS	http://localhost:9200	Comma separated; failover across them
API_KEY / USERNAME+PASSWORD / BEARER_TOKEN	–	Pick one auth mode
VERIFY_CERTS, CA_CERTS, CLIENT_CERT, CLIENT_KEY	true	TLS
REQUEST_TIMEOUT, CONNECT_TIMEOUT, MAX_RETRIES	30, 10, 3	Retries cover 429/502/503/504 and connect errors, with jittered backoff and Retry-After
READ_ONLY	true	Master switch for all write tools
ALLOW_DESTRUCTIVE	false	Second gate for restore_snapshot, reindex, put_mapping, update_settings, delete_by_query, update_by_query
INDEX_ALLOW	*	Glob allow-list
INDEX_DENY	.*,security-*	Glob deny-list; deny wins
DEFAULT_SIZE, MAX_RESULT_SIZE	10, 200	Hit caps
MAX_AGG_BUCKETS	1000	Rejects bucket explosions
SEARCH_TIMEOUT, TERMINATE_AFTER	30s, unset	Per-query guards
MAX_RESPONSE_CHARS, MAX_SOURCE_CHARS	60000, 2000	Token control
AUDIT_LOG_PATH	unset	JSONL record of every tool call and outcome
LOG_LEVEL	INFO	Logs go to stderr, never stdout (stdio transport)

Safety model

Four independent layers, all failing closed:

1. Index policy — allow-list and deny-list checked on every call; deny wins; wildcard writes across the whole cluster refused.
2. Read-only — every write tool refuses unless READ_ONLY=false, and each also requires an explicit confirm=true argument in the call itself.
3. Destructive gate — restore_snapshot, reindex, put_mapping, update_settings, delete_by_query and update_by_query additionally need ALLOW_DESTRUCTIVE=true.
4. Query limits — size clamp, agg bucket cap, agg nesting depth cap, deep-paging rejection, injected search timeout.

Tools return errors as readable text (ERROR (run_query): ...) rather than raising, so the model can correct itself instead of stalling.

Recommended production posture: a dedicated ES API key with read on exactly the allowed indices, READ_ONLY=true, and a separate write-enabled instance only if you actually need reindex/restore from the assistant.

Docker

docker build -t elasticsearch-mcp .
docker run --rm -p 8000:8000 \
  -e ES_MCP_HOSTS=https://es.internal:9200 \
  -e ES_MCP_API_KEY=base64-encoded-api-key \
  elasticsearch-mcp            # runs the streamable-http transport, read-only

The image runs as a non-root user and defaults to ES_MCP_READ_ONLY=true.

Extending

Add a module under src/es_mcp/tools/, expose register(server, ctx), wire it in server.build_server. Use ctx.guard for policy checks and ctx.render for output so limits apply automatically.

License

Apache-2.0. See LICENSE.