Elasticsearch 7.x MCP Server

MCP Server for connecting to the Elasticsearch cluster directly from any MCP Client (such as Claude Desktop, Cursor).

[!IMPORTANT] This fork only supports Elasticsearch 7.x. It includes the @elastic/elasticsearch 7.17 client, and the product check for this client accepts servers older than 7.14. If you are using an Elasticsearch 8.x cluster, use the upstream project @awesome-ai/elasticsearch-mcp forked from here. The 8.x client cannot communicate with a 7.x server, and vice versa.

This server lets agents connect to your Elasticsearch data using the Model Context Protocol. Use natural language to interact with your Elasticsearch index in conversational form.

Features

The tools come in three sets. Only the first set is always exposed; the other two are opt-in via environment variables, so you can provide diagnostics in production without enabling deletion features. Gating is implemented at tool registration: if a tool is disabled, it is not returned in tools/list, so the model cannot call it and incurs no context cost.

Always available — read and write data

Cluster

• elasticsearch_health: cluster health, optionally down to the index level

• cluster_info: cluster name, Elasticsearch version, and build flavor

Index operations

• index names: list indexes, optionally filtered by an Elasticsearch wildcard (log-*)

• create_index: create an index, optionally with settings and mappings

• reindex: copy an index, optionally filtered by a query or transformed with a script

• get_aliases: show which aliases point to which indexes

Mappings

• get_mappings: shows the fields in an index as dot‑separated paths with their types, followed by the raw mapping

• create_mapping: create or update the mapping of an index

Search and data

• search: run a query DSL search, injecting highlighting across all text fields — including nested ones — unless the query provides its own highlight

• count: count matching documents without transferring them

• get_document: fetch a document by ID

• bulk: index multiple documents at once

Templates

• create_index_template: create or update a composable index template

• get_index_template: read index templates

Tasks

• get_task: get the progress of a long‑running task, such as the one returned by reindex

ES_ADMIN_TOOLS=true — Diagnostics (read-only)

These tools only read data, so it is safe to enable them in production — this is the point of this set: a model, without someone logging into the cluster, can explain why an index is unhealthy.

• explain_allocation: explain why a shard is unassigned, including each allocator's decision

• list_shards: show shard‑level state, starting with the replicas that are not STARTED

• list_nodes: heap, CPU, load, and disk pressure for each node

• get_index_stats: per‑index counters — size, segments, indexing, search, merges

• get_index_settings: an index's settings (refresh_interval, replicas, read‑only block)

• get_cluster_settings: cluster settings that were overridden at runtime

• list_tasks: what the cluster is currently running

ES_ALLOW_DESTRUCTIVE=true — irreversible

Designed for a staging environment, off by default so production cannot access them at all.

• delete_index: delete an index and its data

• delete_document: delete a document by ID

• delete by query: delete all documents matching a query — asynchronously, returns a task ID and continues in the background

• delete_index_template: delete an index template

Even when this flag is on, these tools refuse wildcard patterns, comma‑separated lists, *, and _all: they operate only on one named index at a time. A model that mistakes logs-* for a single index gets a refusal instead of an emptied cluster.

How it works

1. The MCP client analyzes your request and determines which Elasticsearch operations are needed.

2. The MCP server performs those operations (listing indexes, fetching mappings, running searches).

3. The MCP client processes the results and presents them in a friendly format.

Related MCP server: Elasticsearch 7.x MCP Server

Getting started

Prerequisites

• An Elasticsearch 7.x instance (tested against 7.8; the 7.17 client supports 6.8 through 7.x)

• Elasticsearch credentials — an API key, or a username and password

• An MCP client: Claude Code, Claude Desktop, Codex, Cursor, or anything else that speaks MCP over stdio.

Authenticate once to GitHub Packages

[!IMPORTANT] This package is published to GitHub Packages, not npmjs.com, and GitHub Packages requires a token even for public packages. Until you add one, every install below fails with a 401. Put it in your user‑level ~/.npmrc:

@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN is a personal access token with the read:packages scope.

Keep it in your ~/.npmrc, not in a project file — a token committed to a repository is a leaked token, and some package managers refuse to read one from a project file.

Connecting to your client

Every example below sets ES_HOST and ES_API_KEY. To use Basic Auth instead, swap in ES_USERNAME/ES_PASSWORD. Add ES_ADMIN_TOOLS=true to enable the diagnostic tools, and set ES_INSTANCE_LABEL when you declare more than one instance — see Configuration Options.

claude mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  --env ES_ADMIN_TOOLS=true \
  -- npx -y @agrica/elasticsearch7-mcp

Then /mcp in a session lists the server and its tools.

Two details that are easy to get wrong:

• Everything after -- is the command that runs the server; without it, Claude Code would try to parse -y as one of its own flags.

• Do not place the server name directly after --env — the CLI reads it as another KEY=value pair and rejects it. In the example above, the server name comes first, which is why it works.

The server is added at the local scope, so it only loads in the current project. Add --scope user to make it global, or --scope project to write it into .mcp.json and share it with your team. Be aware that a committed .mcp.json would still contain your API key, so prefer a user scope for credentials.

Edit claude_desktop_config.json — Settings → Developer → Edit Config opens it, or locate it at %APPDATA%\Claude\ on Windows and ~/Library/Application Support/Claude/ on macOS:

{
  "mcpServers": {
    "elasticsearch7": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://your-cluster:9200",
        "ES_API_KEY": "your-api-key",
        "ES_ADMIN_TOOLS": "true"
      }
    }
  }
}

Restart Claude Desktop afterwards; it only reads that file at startup.

codex mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  -- npx -y @agrica/elasticsearch7-mcp

Or write it manually into ~/.codex/config.toml. Note that Codex uses mcp_servers for which the table assignment is mcp_servers with an underscore, and the environment is placed in its own sub‑table rather than inline:

[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]

[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"

/mcp inside Codex confirms that the server is loaded.

The server is a plain stdio MCP server, so anything on the MCP client list works. It needs three things: the command npx, the arguments -y @agrica/elasticsearch7-mcp, and the ES_* variables in the environment. It never listens on a port and writes nothing but MCP protocol to stdout — diagnostics go to stderr.

Configuration

The Elasticsearch MCP Server supports configuration options for connecting to Elasticsearch:

[!NOTE] You must provide either an API key or both a username and password for authentication.

[!WARNING] ES_ADMIN_TOOLS and ES_ALLOW_DESTRUCTIVE have no un‑prefixed legacy alias, unlike the connection variables above. This is intentional: a bare ADMIN_TOOLS or ALLOW_DESTRUCTIVE in the environment is far too easy to set accidentally for something that controls whether destructive actions are reachable.

Both accept true or 1; anything else — including an unset variable — means off.

Result size

A tool result is capped at 32 KB (ES_MAX_RESULT_BYTES). This matters on a logging cluster: before the cap, one list_shards call over a year of daily indices returned 385 KB — approximately 96,000 tokens — in a single answer, which exceeds what most sessions can handle.

When a result is trimmed, it reports that, indicates how much was omitted, and tells you how to ask a smaller question. Three tools shape their answers around this limit:

• list_indices and list_shards return a readable summary; the same rows are available as text behind verbose.

• search caps size at 100 per call and tells you the from to use for paging.

• get_mappings lists the fields first and the raw mapping second, so an index with a thousand fields still answers the question it was asked.

Four tools — list_indices, list_shards, get_index_settings, and get_mappings — also provide their answer as typed structured output, so a client can read the rows instead of parsing the text. It is assembled from whatever space is left after the readable answer, and reports returned against total so a partial listing can be detected by number.

Run pnpm run measure against the built output to see the current values for your own configuration.

Labeling multiple instances

Most setups declare this server more than once — one entry per cluster. The entries are otherwise identical, so a client shows two servers with the same name and no way to tell them apart. ES_INSTANCE_LABEL becomes the server’s display title, and it is the natural place to indicate which environment an entry targets:

{
  "mcpServers": {
    "es7-prod": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-prod:9200",
        "ES_API_KEY": "prod-key",
        "ES_INSTANCE_LABEL": "production",
        "ES_ADMIN_TOOLS": "true"
      }
    },
    "es7-staging": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-staging:9200",
        "ES_API_KEY": "staging-key",
        "ES_INSTANCE_LABEL": "staging",
        "ES_ADMIN_TOOLS": "true",
        "ES_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

이 구성 쌍이 의도된 형태입니다. 진단은 양쪽 모두에, 삭제는 스테이징에서만 허용합니다. 프로덕션에서는 비정상 인덱스를 설명하는 도구만 제공하고, 데이터를 제거할 수 있는 도구는 절대 노출하지 않습니다. 등록되지 않은 도구는 모델이 호출할 수 없기 때문입니다.

이 라벨은 시작 시 stderr에도 출력됩니다. 클라이언트가 연결을 보고했는데 어느 클러스터가 응답했는지 알 수 없다면 stderr를 확인하면 됩니다.

여러 URL 구성

고가용성과 부하 분산을 위해 여러 Elasticsearch 노드를 구성할 수 있습니다.

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agrica/elasticsearch7-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

클라이언트는 구성된 노드 사이의 장애 조치와 부하 분산을 자동으로 처리합니다.

Docker로 실행하기

각 릴리스는 멀티 아키텍처 이미지(linux/amd64, linux/arm64)를 GitHub Container Registry에 게시합니다.

docker pull ghcr.io/agrica/elasticsearch7-mcp:latest

서버는 stdio를 사용하므로 컨테이너에는 인터랙티브 stdin이 필요하고 공개된 포트는 없습니다. MCP 클라이언트에서는 다음과 같이 지정합니다.

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_HOST",
        "-e", "ES_API_KEY",
        "ghcr.io/agrica/elasticsearch7-mcp:latest"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

[!NOTE] npm 패키지와 마찬가지로 이미지는 GitHub Packages에 있습니다. 저장소가 공개되어 있어도 이미지를 가져오려면 read:packages 범위가 있는 토큰이 필요합니다.

이미지에는 공개된 포트나 볼륨이 필요하지 않습니다. stdio로 통신하며, MCP 클라이언트가 stdin과 stdout을 소유합니다.

예시 쿼리

[!TIP] 다음은 MCP 클라이언트로 시도해 볼 수 있는 자연어 쿼리 예시입니다.

클러스터 관리

• "내 Elasticsearch 클러스터의 상태는 어떤가요?"

• "내 클러스터에는 활성 노드가 몇 개 있나요?"

인덱스 작업

• "내 Elasticsearch 클러스터에 어떤 인덱스가 있나요?"

• "'users'라는 인덱스를 샤드 3개, 복제본 1개로 생성해 주세요."

• "'old_index'에서 'new_index'로 데이터를 다시 인덱싱해 주세요."

매핑 관리

• "'products' 인덱스의 필드 매핑을 보여 주세요."

• "'products' 인덱스에 'tags'라는 keyword 유형 필드를 추가해 주세요."

검색 및 데이터 작업

• "지난달 $500가 넘는 모든 주문을 찾아 주세요."

• "어떤 제품이 5점짜리 리뷰를 가장 많이 받았나요?"

• "'customers' 인덱스에 이 고객 레코드들을 일괄 가져오세요."

템플릿 관리

• "'logs-*' 패턴의 로그용 인덱스 템플릿을 생성해 주세요."

• "나의 인덱스 템플릿을 모두 보여 주세요."

진단 (ES_ADMIN_TOOLS=true 필요)

• "'logs-2026' 인덱스가 yellow 상태인데 왜 샤드가 할당되지 않았나요?"

• "디스크 웟터마크에 가까운 노드가 있나요?"

• "내 인덱스 중 가장 큰 것은 무엇이며, 삭제된 문서는 얼마나 되나요?"

• "이 클러스터에서 누군가 샤드 할당을 잠근 것이 있나요?"

• "리인덱스가 아직 실행 중인가요?"

파괴적 작업 (requires ES_ALLOW_DESTRUCTIVE=true 필요)

• "'smoke-test-source' 인덱스를 삭제해 주세요."

• "'logs-archive'에 있는 2024년 이전 문서를 모두 제거해 주세요."

문제 해결

버그를 발견했거나 필요한데 없는 도구가 있나요? GitHub 저장소에 이슈를 열어 주세요. 코드를 수정하려면 CONTRIBUTING.md에서 시작하세요.