Elasticsearch MCP 服务器

[!CAUTION] 此 MCP 服务器已弃用，后续仅会接收关键安全更新。 它已被 Elastic Agent Builder 的 MCP 端点取代，该功能适用于 Elastic 9.2.0+ 和 Elasticsearch Serverless 项目。

使用模型上下文协议（MCP）直接从任何 MCP 客户端连接您的 Elasticsearch 数据。

该服务器通过模型上下文协议将代理连接到您的 Elasticsearch 数据，使您能够通过自然语言对话与 Elasticsearch 索引进行交互。

可用工具

• list_indices: 列出所有可用的 Elasticsearch 索引
• get_mappings: 获取特定 Elasticsearch 索引的字段映射
• search: 使用提供的查询 DSL 执行 Elasticsearch 搜索
• esql: 执行 ES|QL 查询
• get_shards: 获取所有或特定索引的分片信息

先决条件

• Elasticsearch 实例
• Elasticsearch 认证凭证（API 密钥或用户名/密码）
• MCP 客户端（如 Claude Desktop、Goose）

支持的 Elasticsearch 版本

兼容 Elasticsearch 8.x 和 9.x 版本。

安装与设置

[!NOTE]

0.3.1 及更早版本通过 npm 安装。这些版本已弃用且不再支持。以下说明仅适用于 0.4.0 及更高版本。

查看 0.3.1 及更早版本的说明，请参阅 v0.3.1 的 README。

此 MCP 服务器以 Docker 镜像形式提供，位于 docker.elastic.co/mcp/elasticsearch，支持 MCP 的 stdio、SSE 和 streamable-HTTP 协议。

不带任何参数运行此容器将显示使用信息：

docker run docker.elastic.co/mcp/elasticsearch

用法: elasticsearch-mcp-server <命令>

命令:
  stdio  启动 stdio 服务器
  http   启动支持可选 SSE 的 streamable-HTTP 服务器
  help   打印此消息或给定子命令的帮助信息

选项:
  -h, --help     打印帮助
  -V, --version  打印版本

使用 stdio 协议

MCP 服务器需要设置环境变量：

• ES_URL: Elasticsearch 集群的 URL
• 认证使用 API 密钥或基本认证：
  • API 密钥: ES_API_KEY
  • 基本认证: ES_USERNAME 和 ES_PASSWORD
• 可选地，ES_SSL_SKIP_VERIFY 设为 true 可在连接 Elasticsearch 时跳过 SSL/TLS 证书验证。提供自定义证书的功能将在后续版本中添加。

使用以下命令以 stdio 模式启动 MCP 服务器：

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

Claude Desktop 的配置如下：

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

使用 streamable-HTTP 和 SSE 协议

注意：推荐使用 streamable-HTTP，因为 SSE 已弃用。

MCP 服务器需要设置环境变量：

• ES_URL: Elasticsearch 集群的 URL
• 认证使用 API 密钥或基本认证：
  • API 密钥: ES_API_KEY
  • 基本认证: ES_USERNAME 和 ES_PASSWORD
• 可选地，ES_SSL_SKIP_VERIFY 设为 true 可在连接 Elasticsearch 时跳过 SSL/TLS 证书验证。提供自定义证书的功能将在后续版本中添加。

使用以下命令以 http 模式启动 MCP 服务器：

docker run --rm -e ES_URL -e ES_API_KEY -p 8080:8080 docker.elastic.co/mcp/elasticsearch http

如果某些执行环境不允许向容器传递参数，可以使用 CLI_ARGS 环境变量传递：docker run --rm -e ES_URL -e ES_API_KEY -e CLI_ARGS=http -p 8080:8080...

streamable-HTTP 端点为 http:<host>:8080/mcp。健康检查端点为 http:<host>:8080/ping

Claude Desktop（仅支持 stdio 协议的免费版）配置：

1. 安装 mcp-proxy（或等效工具），它将桥接 stdio 到 streamable-http。可执行文件将安装在 ~/.local/bin：

   uv tool install mcp-proxy
   

2. 将以下配置添加到 Claude Desktop：

   {
     "mcpServers": {
       "elasticsearch-mcp-server": {
         "command": "/<home-directory>/.local/bin/mcp-proxy",
         "args": [
           "--transport=streamablehttp",
           "--header", "Authorization", "ApiKey <elasticsearch-API-key>",
           "http://<mcp-server-host>:<mcp-server-port>/mcp"
         ]
       }
     }
   }