Elasticsearch 7.x MCP Server

用于从任何 MCP 客户端（如 Claude Desktop、Cursor）直接连接你的 Elasticsearch 集群的 MCP 服务器。

[!IMPORTANT] 这个 fork 仅面向 Elasticsearch 7.x。 它将 @elastic/elasticsearch 客户端锁定在 7.17 版本，该版本的 product check 会接受早于 7.14 的服务端。对于 Elasticsearch 8.x 集群，请使用上游项目 @awesome-ai/elasticsearch-mcp，本 fork 亦衍生自此。8.x 客户端无法与 7.x 服务端通信，反之亦然。

该服务器通过 Model Context Protocol 将代理连接到你的 Elasticsearch 数据。它允许你通过自然语言对话与 Elasticsearch 索引交互。

功能概览

工具分为三组。只有第一组始终开放；另外两组通过环境变量选择启用，因此生产环境可以在不提供删除能力的情况下提供诊断。控制发生在注册时：被禁用的工具永远不会出现在 tools/list 中，模型无法调用它，也不会在代理上下文中占用任何成本。

始终可用 —— 读写数据

集群

• elasticsearch_health: cluster health, optionally down to index level

• cluster_info：群集名称、Elasticsearch 版本和构建风格

索引操作

• list_indices：按 Elasticsearch 通配符过滤列出索引

• create_index：创建索引，可含可选的 settings 和 mappings

• reindex：复制一个索引，可通过查询过滤或脚本转换

• get_aliases：哪些别名指令哪些索引

mappings

• get_mappings：索引的字段，先后以 dotted paths 及其类型显示，再显示原始 mapping

• create_mapping：创建或更新索引的映射

搜索和数据

• search：运行 queries DSL 搜索，自动在全部 text field 上注入高亮——包括嵌套字段——除非查询自带 highlight

• count：匹配的文档数量，不传输文档内容

• get_document：按 id 获取一个 document

• bulk：一次索引多个 document

模板

• create_index_template:创建或更新 composable index template

• get_index_template:读取 index templates

Tasks

• get_task：查询关于长任务（如 reindex 返回的任务）的进度

ES_ADMIN_TOOLS=true —— 诊断功能（只读）

这些工具仅读取，因此可以在生产中安全启用——这也是这组工具的意义所在：代理可以解释为什么某个索引不健康，任何人都无需登录集群。

• explain_allocation: 为什么某个分片未分配，每个 allocator 做作什么决策

• list_shards: 分片级状态，把不是 STARTED 的副本列在最前

• list_nodes: 每个节点的堆内存、CPU、负载和磁盘压力

• get_index_stats: Per-index 计数器 —— size, segments, indexing, search, merges

• get_index_settings: 索引的 settings（refresh_interval, replicas, read-only blocks）

• get_cluster_settings: 在运行中被修整的 cluster settings

• list_tasks: 集群目前在执行什么任务

ES_ALLOW_DESTRUCTIVE=true —— 不可逆操作

适合部署环境用于环境本身，并且默认关闭，使生产环境无法触及这些操作。

• delete_index：删除索引及其 data

• delete_document：按 id 删除一个 document

• delete_by_query：删除所有 matching query 的 document — 异步，返回 task id，删除会在后台继续

• delete_index_template：删除 index template

即使开启此 flag，它们也会拒绝 wildcard、逗号分隔列表、* 和 _all：一次只操作一个指定的可引用索引。一个把 logs-* 误认为单个索引的模型只会收到拒绝，而不是会让集群被清空。

工作原理

1. MCP 客户端分析你的请求，并决定需要哪些 Elasticsearch 操作。

2. MCP 服务器执行这些操作（列出 indices、获取 mapping、执行 search）。

3. MCP 客户端处理结果并以用户友好的格式呈现。

Related MCP server: Elasticsearch 7.x MCP Server

快速开始

前置条件

• 一个 Elasticsearch 7.x 实例（针对 7.8 验证；7.17 以及客户端支持 6.8 到 7.x）

• Elasticsearch 凭据——API key，或者 username/password

• 一个 MCP 客户端：Claude Code、Claude Desktop、Codex、Cursor 或任何可以通过 stdio 与 MCP 通信的客户端

向 GitHub Packages 作一次性认证

[!IMPORTANT] 本包发布到的是 GitHub Packages，而不是 npmjs.com。GitHub Packages 即便是公开的包也要 token。如果你不加 token，以下每次以及安装都会以 401 失败。请将其写入 user-level 的 ~/.npmrc：

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

YOUR_GITHUB_TOKEN 是一个具有 read:packages scope 的 personal access token。

请把它保留在你自己的 ~/.npmrc，不要放在 project file 中——提交到仓库的 token 就是泄漏的 token，而且某些包管理器可能拒绝从此处读取 token。

连接到你的 client

下面的每个示例都会设置 ES_HOST 和 ES_API_KEY。如果想改用 basic auth，请替换成 ES_USERNAME/ES_PASSWORD；如需诊断工具则设置 ES_ADMIN_TOOLS=true；声明多个实例时，设置 ES_INSTANCE_LABEL——见 配置选项。

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

然后在会话中输入 /mcp 即可看到该 Server。它的工具列表可被列出。

这两个细节容易被弄错：

• -- 后面的所有内容是运行 Server 的命令——如果没有它，Claude Code 会尝试把 -y 当成它自己的 flag 来解析。

• 不要紧跟着 --env 后面立刻放 Server name —— CLI 会把下面接受成另一个 KEY=value 对并拒绝。上面 name 在前，所以才会成功。

该 Server 以 local scope 添加，因此只加载于当前 project。要全局可用加 --scope user，或用 --scope project 写入 .mcp.json 并分享给团队——注意，提交 .mcp.json 会带上你的 API key，所以 is prefer 使用 user scope 放置 credentials。

编辑 claude_desktop_config.json — 可通过 Settings > Developer > Edit Config 打开，在 Windows 上位于 %APPDATA%\Claude\，在 macOS 上位于 ~/Library/Application Support/Claude/：

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

随后重启 Claude Desktop；它只会在启动时读取该文件。

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

或者手动编辑 ~/.codex/config.toml。注意 Codex 将表名拼写为 mcp_servers（带下划线），并且环境变量放在它自己的子表中，而不是内联：

[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"

在 Codex 中查看 /mcp 可确认 Server 已加载。

该 Server 是一个纯 stdio MCP Server，因此任何支持 MCP 客户端的应用 都可以使用。它需要三样东西：命令 npx、参数 -y @agrica/elasticsearch7-mcp，以及环境中的 ES_* 变量。它不监听端口，不往 stdout 写非 MCP 协议内容——diagnostic 信息只发暗去 stderr。

配置选项

Elasticricsearch MCP Server 支持以下配置选项来连接你的 Elasticsearch：

[!NOTE] 必须提供 API key 或 username 和 password 两者之一来进行身份验证。

[!WARNING] ES_ADMIN_TOOLS 和 ES_ALLOW_DESTRUCTIVE 没有像上面的连接变量那样提供不带前缀的旧别名。这是设计上故意的：一个无前缀的 ADMIN_TOOLS 或 ALLOW_DESTRUCTIVE 放在环境中，对于决定是否 enable delete 的开关而言，实在是太容易误设了。

两者都接受 true 或 1；其他任意值（包括未设置变量）都表示关闭。

结果大小

单个工具结果上限为 32 KB（由 ES_MAX_RESULT_BYTES 控制）。这在 logging 集群上很关键：超过上限之前，一次 list_shards 调用可能对一整年的 daily indices 返回 385 KB——约为 96,000 个 token——这在单次答复中可能会超过大多数会话能承受的量。

当结果被截断时，它会说明已截断、被省略了多少，并告诉用户如何提出更小的问题。三个工具会以此为基础来组织返回内容：

• list_indices 和 list_shards 返回容易阅读的 summary；同样的 rows 可作为文本由 verbose 提供。

• search 每次调用把 size 限制为 100，并返回用于后续分页的 from。

• get_mappings 先列出 fields 再列出 raw mapping，因此即使带有上千个 field 的 index 也能回答所问的问题。

四个工具—— list_indices、list_shards、get_index_settings 和 get_mappings —— 除了可读文本，还会以类型风格的结构化输出返回数据，因此客户端可以直接读取 rows，无需解析文本。该结构化结果由可读答案剩余部分的空间组装而成，用 returned 对照 total 显示，使得部分列表也能作为数字被看到。

运行 pnpm run measure 针对构建出的结果检查 static 当前实际数据。

为多实例添加标签

大多数环境会不止一次为 server 声明多个实例（每个 cluster 一个 entry）。这些 entry 看起来完全相同，客户端会显示两个同名的 server，无法区分。 ES_INSTANCE_LABEL 会用作 server 的显示标题，因此它很适合用来标识某个 entry 对应的是哪个环境：

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

这对配置是预期形态：**两侧都提供诊断，删除操作仅在 staging 上提供。**模型无法调用从未注册过的东西。

该标识也会在启动时打印到 stderr。如果某个 client 报告连接问题，但你不能确定是哪个集群在响应，就去 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 运行

每个版本都会向 GitHub Container Registry 发布一个多架构镜像（linux/amd64、linux/arm64）：

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

该 server 通过 stdio 通信，因此容器需要一个交互式 stdin，并且不需要公开任何端口。在 MCP client 中：

{
  "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 范围的 token，即使仓库是公开的也如此。

该镜像无需公开发布端口，也无需卷：它通过 stdio 通信，并由 MCP client 拥有其 stdin 和 stdout。

查询示例

[!TIP] 以下是一些您可以在 MCP client 中尝试的自然语言查询。

集群管理

• “我的 Elasticsearch 集群的健康状态如何？”

• “我的集群中有多少个 active 节点？”

索引操作

• “我的 Elasticsearch 集群中有哪些索引？”

• “创建一个名为 ‘users’ 的新索引，分片数为 3，副本数为 1。”

• “将数据从 ‘old_index’ 重新索到 ‘new_index’。”

映射管理

• “显示 ‘products’ 索引的字段映射。”

• “向 ‘products’ 索引添加一个名为 ‘tags’ 的 keyword 类型字段。”

搜索与数据操作

• “查找上月所有超过 $500 的订单。”

• “哪些产品收到了最多的 5 星评价？”

• “将这批客户记录批量导入到 ‘customers’ 索引中。”

模板管理

• “为模式为 ‘logs-*’ 的日志创建一个索引模板。”

• “显示我所有的索引模板。”

诊断（需要 ES_ADMIN_TOOLS=true）

• “‘logs-2026’ 索引显示为黄色——为什么它的分片未分配？”

• “是否有任意节点接近磁盘水位？”

• “我的哪个索引最大，其中有多少是已删除文档？”

• “是否有人在此集群上 Web房分片分配？”

• “是否有重新索仍在运行？”

破坏性操作（需要 ES_LLOW_DESTRUCTIVE=true）

• “删除 ‘smoke-test-source’ 索引。”

• “从 ‘logs-archive’ 中清除所有早于 2046 的文档。”

故障排查

发现了一个 bug 或需要有一个不存在的工具？请在 GitHub 仓库中打开 issue。要参与代码开发，请从 CONTIRBUTING.md 开始。