Elasticsearch MCP 服务器

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

使用 Elasticsearch MCP 服务器为 AI 代理提供支持

Elasticsearch MCP 服务器通过 Model Context Protocol (MCP) 将您的 AI 代理与 Elasticsearch 数据连接起来。 它使您能够以自然语言与 Elasticsearch 索引进行交互，允许代理在无需自定义 API 的情况下查询、分析和检索数据。

请按照以下步骤从 AWS Marketplace 部署并配置 Elasticsearch MCP 服务器容器镜像。

开始之前

在开始之前，请确保您具备以下条件：

• 一个可从您的 AWS 环境访问的 Elasticsearch 集群（版本 8.x 或 9.x）
• Elasticsearch 身份验证凭据：
  • API 密钥，或
  • 用户名 和密码对
• 在您的 AWS 环境中已安装并运行 Docker（例如，在 EC2 实例上或容器服务中）
• 已配置好一个 MCP 客户端（如 Claude Desktop、Cursor、VS Code 或其他兼容 MCP 的工具）
• 您的部署环境与 Elasticsearch 集群之间具有网络连通性

[!NOTE]

本说明适用于 Elasticsearch MCP 服务器 0.4.0 及更高版本。 对于 0.3.1 及更早版本，请参阅 v0.3.1 的 README。

部署 Elasticsearch MCP 服务器

Elasticsearch MCP 服务器以 Docker 容器镜像的形式提供，可在 AWS Marketplace 中获取。您可以使用 stdio 协议（用于直接客户端连接）或 streamable-HTTP 协议（用于基于 Web 的集成）来运行它。

选择协议

该服务器支持两种协议：

• stdio：MCP 客户端与服务器之间的直接通信。当您的客户端支持 stdio 并在同一环境中运行时，请使用此协议。
• streamable-HTTP：基于 HTTP 的协议，推荐用于 Web 集成、有状态会话以及并发客户端。

注意： 服务器发送事件 (SSE) 已弃用。请改用 streamable-HTTP。

配置 stdio 协议

当您的 MCP 客户端直接连接到服务器进程时，请使用 stdio 协议。

设置 stdio 模式的环境变量

设置以下环境变量：

• ES_URL：您的 Elasticsearch 集群的 URL（例如，https://your-cluster.es.amazonaws.com:9200）
• 对于身份验证，使用以下选项之一：
  • API 密钥：将 ES_API_KEY 设置为您 Elasticsearch 的 API 密钥
  • 基本身份验证：将 ES_USERNAME 和 ES_PASSWORD 设置为您的 Elasticsearch 凭据
• （可选）ES_SSL_SKIP_VERIFY：设置为 true 以在连接到 Elasticsearch 时跳过 SSL/TLS 证书验证。仅在开发或测试环境中使用此选项。

以 stdio 模式运行容器

以 stdio 模式启动 MCP 服务器：

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

配置 Claude Desktop

将此配置添加到您的 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>"
      }
    }
  }
}

将 <elasticsearch-cluster-url> 替换为您的 Elasticsearch 集群 URL，将 <elasticsearch-API-key> 替换为您的 API 密钥。

配置 streamable-HTTP 协议

当您需要进行基于 Web 的集成，或需要支持多个并发客户端时，请使用 streamable-HTTP 协议。

设置 HTTP 模式的环境变量

设置与 stdio 协议相同的环境变量：

• ES_URL：您的 Elasticsearch 集群的 URL
• 对于身份验证，使用以下选项之一：
  • API 密钥：将 ES_API_KEY 设置为您 Elasticsearch 的 API 密钥
  • 基本身份验证：将 ES_USERNAME 和 ES_PASSWORD 设置为您的 Elasticsearch 凭据
• （可选）ES_SSL_SKIP_VERIFY：设置为 true 以在连接时跳过 SSL/TLS 证书验证。

以 HTTP 模式运行容器

以 HTTP 模式启动 MCP 服务器：

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

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

使用 HTTP 代理配置 Claude Desktop

如果您使用的是仅支持 stdio 协议的 Claude Desktop（免费版），可以使用 mcp-proxy 将 stdio 桥接到 streamable-HTTP：

1. 安装 mcp-proxy：

   uv tool install mcp-proxy
   

   如需其他安装选项，请参阅 mcp-proxy/README.md。

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

   将 <home-directory>、<elasticsearch-API-key>、<mcp-server-host> 和 <mcp-server-port> 替换为您自己的值。

验证连接

配置好您的 MCP 客户端后，请验证连接是否正常工作：

1. 启动您的 MCP 客户端（例如，Claude Desktop 或 Cursor）。
2. 检查 Elasticsearch MCP 服务器是否出现在可用的 MCP 服务器列表中。
3. 通过您的代理界面测试一个简单的查询，以确认它可以访问您的 Elasticsearch 索引。

如果连接失败，请检查：

• 您的 Elasticsearch 集群 URL 是否正确，并且可以从您的 AWS 环境访问
• 您的身份验证凭据是否有效，并具有必要的权限
• 容器与 Elasticsearch 集群之间是否存在网络连通性（检查安全组和网络 ACL）
• Docker 是否正在运行，容器是否成功启动（使用 docker logs <container-id> 查看容器日志）

监控健康与状态

使用以下方法监控 Elasticsearch MCP 服务器的健康状况和正常运行：

检查容器状态

验证容器是否正在运行：

docker ps | grep elasticsearch-mcp-server

容器应出现在列表中，状态为 Up。

测试健康端点（HTTP 模式）

如果您使用的是可流式传输的 HTTP 协议，请测试健康检查端点：

curl http://<host>:8080/ping

成功的响应会返回 pong，表明服务器正在运行且健康。

查看容器日志

查看容器日志以识别任何问题：

docker logs <container-id>

查找与以下内容相关的错误消息：

• Elasticsearch 连接失败
• 身份验证错误
• 网络连接问题

验证 Elasticsearch 连接

从容器内测试与您的 Elasticsearch 集群的连接：

docker exec <container-id> curl -k -u <username>:<password> <ES_URL>

或者使用 API 密钥：

docker exec <container-id> curl -k -H "Authorization: ApiKey <api-key>" <ES_URL>

成功的响应表示容器可以访问您的 Elasticsearch 集群。

安全与敏感信息

Elasticsearch MCP 服务器会安全地处理身份验证凭据：

凭据存储

• API 密钥和密码：仅存储在传递给容器的环境变量中。它们不会持久化到磁盘或记录到日志中。
• 环境变量：在运行容器时设置。在生产环境中，请使用 AWS Secrets Manager 或 AWS Systems Manager Parameter Store 来安全管理凭据。

数据加密

• 传输中：当您的 ES_URL 使用 https:// 协议时，MCP 服务器会通过 HTTPS 与 Elasticsearch 通信。请确保您的 Elasticsearch 集群已启用 SSL/TLS。
• 静态数据：容器不会在本地存储数据。所有数据都保留在您的 Elasticsearch 集群中，使用集群的加密设置。

最佳实践

• 定期轮换 API 密钥（生产环境每 30–90 天一次）
• 使用具有最小必要权限的 API 密钥（尽可能只授予对特定索引的只读访问权限）
• 切勿将凭据提交到版本控制系统或在日志中共享
• 使用 AWS Secrets Manager 或 Parameter Store 在运行时注入凭据，而不是将其硬编码。

AWS 服务配额

Elasticsearch MCP 服务器作为容器在您的 AWS 环境中运行。请考虑以下 AWS 服务配额：

• EC2 实例限制：如果在 EC2 上运行，请确保您的实例类型能够支持预期的工作负载。
• Elastic Container Service (ECS)：如果使用 ECS，请查看 ECS 服务配额。
• Elastic Kubernetes Service (EKS)：如果使用 EKS，请查看 EKS 服务配额。
• 网络带宽：确保容器与 Elasticsearch 集群之间的网络带宽充足。

如需申请提高配额，请使用 AWS 服务配额控制台 或参考 AWS 通用参考指南。

可用工具

连接成功后，MCP 服务器会向您的代理提供以下工具：

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

您的代理可以使用这些工具，通过自然语言对话与您的 Elasticsearch 数据进行交互。

后续步骤

• 了解 Elastic 平台中可用的人工智能功能
• 探索 Agent Builder，使用 Elasticsearch 构建自定义 AI 代理

mcp-server-elasticsearch 快速上手指南

⚠️ 重要提示：该 MCP 服务器已标记为弃用（Deprecated），未来仅接收关键安全更新。官方推荐使用 Elastic 9.2.0+ 或 Elasticsearch Serverless 项目中的 Elastic Agent Builder 替代。以下指南仅适用于仍需使用此版本的场景。

环境准备

在开始之前，请确保满足以下条件：

• Elasticsearch 集群：版本 8.x 或 9.x，且可从您的部署环境（如 AWS EC2、本地 Docker）访问。
• 认证凭据：具备以下任一组合：
  • Elasticsearch API Key（推荐）
  • 用户名和密码
• Docker 环境：已安装并运行 Docker。
• MCP 客户端：已配置支持 MCP 的工具（如 Claude Desktop、Cursor、VS Code 等）。
• 网络连通性：确保运行容器的环境与 Elasticsearch 集群之间网络通畅。

安装与配置步骤

该工具以 Docker 容器形式提供，支持 stdio（直接连接）和 streamable-HTTP（Web 集成）两种协议。

方案 A：使用 stdio 协议（推荐用于本地客户端）

适用于 MCP 客户端与服务器在同一环境直接通信的场景（如 Claude Desktop 本地版）。

1. 设置环境变量 在终端中导出以下变量（替换为您的实际值）：

   export ES_URL="https://your-cluster.es.amazonaws.com:9200"
   export ES_API_KEY="your_elasticsearch_api_key"
   # 若使用账号密码认证，则使用以下两行代替 ES_API_KEY
   # export ES_USERNAME="your_username"
   # export ES_PASSWORD="your_password"
   
   # 开发测试环境下若需跳过 SSL 验证（生产环境请勿使用）
   # export ES_SSL_SKIP_VERIFY="true"
   

2. 运行容器 执行以下命令启动服务：

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

3. 配置 MCP 客户端（以 Claude Desktop 为例） 编辑 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>"
         }
       }
     }
   }
   

   请将 <elasticsearch-cluster-url> 和 <elasticsearch-API-key> 替换为您的实际地址和密钥。

---

方案 B：使用 streamable-HTTP 协议（推荐用于 Web 集成或多客户端）

适用于需要独立服务进程或通过 HTTP 暴露接口的场景。

1. 设置环境变量 同方案 A，设置 ES_URL 和认证信息。

2. 运行容器 启动 HTTP 模式服务（默认端口 8080）：

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

   服务地址：http://<host>:8080/mcp 健康检查地址：http://<host>:8080/ping

3. 配置 MCP 客户端（通过代理连接） 若客户端仅支持 stdio（如 Claude Desktop 免费版），需使用 mcp-proxy 桥接：

   • 安装代理工具：

     uv tool install mcp-proxy
     

   • 修改客户端配置：

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

基本使用

配置完成后，重启您的 MCP 客户端（如 Claude Desktop 或 Cursor）。

1. 验证连接 在客户端中确认 elasticsearch-mcp-server 已出现在可用服务器列表中。

2. 自然语言交互示例 直接在对话框中输入自然语言指令，AI Agent 将自动调用底层工具操作 Elasticsearch。

   • 查询索引列表：

     "列出所有的 Elasticsearch 索引。" (对应工具：list_indices)

   • 执行搜索：

     "搜索 'logs-' 开头的索引中，状态码为 500 的错误日志。" (对应工具：search)

   • 执行 ES|QL 查询：

     "使用 ES|QL 统计过去一小时每个用户的请求数量。" (对应工具：esql)

   • 查看映射结构：

     "显示 'products' 索引的字段映射结构。" (对应工具：get_mappings)

可用工具列表

Agent 可直接调用的核心功能包括：

• list_indices: 列出所有索引
• get_mappings: 获取指定索引的字段映射
• search: 执行 DSL 搜索查询
• esql: 执行 ES|QL 查询
• get_shards: 获取分片信息