Elasticsearch MCP 服务器

[!警告] 此 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。

安装与设置

[!注意]

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

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

此 MCP 服务器作为 Docker 镜像提供，位于 docker.elastic.co/mcp/elasticsearch，支持 MCP 的 stdio、SSE 和可流式传输的 HTTP 协议。

不带参数运行此容器将输出使用消息：

docker run docker.elastic.co/mcp/elasticsearch

使用方法: elasticsearch-mcp-server <COMMAND>

命令:
  stdio  启动一个 stdio 服务器
  http   启动一个可流式传输的 HTTP 服务器，可选带有 SSE 支持
  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>"
    }
   }
 }
}

使用可流式传输的 HTTP 和 SSE 协议

注意：推荐使用可流式传输的 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...

可流式传输的 HTTP 端点位于 http:<host>:8080/mcp。还有一个健康检查位于 http:<host>:8080/ping

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

1. 安装 mcp-proxy（或等效工具），它将桥接 stdio 到可流式传输的 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"
         ]
       }
     }
   }