Elasticsearch MCP Server

Elasticsearch MCP 服务

注意

此 MCP 服务已弃用，今后仅会收到关键安全更新。 它已被 Elastic Agent Builder MCP 端点取代，该端点适用于 Elastic 9.2.0+ 和 Elasticsearch Serverless 项目。

将 Elasticsearch MCP 服务用于 AI Agent

Elasticsearch MCP 服务使用 Model Context Protocol（MCP）将 AI Agent 连接到 Elasticsearch 数据。 它支持使用自然语言与 Elasticsearch 索引交互，让 Agent 无需自定义 API 即可查询、分析和检索数据。

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

开始之前

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

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

说明

这些说明适用于 Elasticsearch MCP Server 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 集成、有状态会话和并发客户端。

**注意：**Server-Sent Events（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 密钥
  • Basic 身份验证：将 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

如果你使用的 Claude Desktop（免费版）仅支持 stdio 协议，可使用 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 Server 是否出现在可用的 MCP 服务列表中。
3. 通过 Agent 界面执行简单查询，确认其能够访问 Elasticsearch 索引。

如果连接失败，请检查：

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

监控运行状况和状态

使用以下方法监控 Elasticsearch MCP Server 的运行状况和正常运行情况：

检查容器状态

确认容器正在运行：

docker ps | grep elasticsearch-mcp-server

容器应显示在列表中，状态为 Up。

测试健康检查端点（HTTP 模式）

如果使用 streamable-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 Server 会安全地处理身份验证凭据：

凭据存储

• 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 Server 作为容器运行在您的 AWS 环境中。请考虑以下 AWS 服务配额：

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

如需申请提高配额，请使用 AWS Service Quotas 控制台，或参阅 AWS General Reference Guide。

可用工具

连接后，MCP 服务会向您的 Agent 提供以下工具：

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

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

后续步骤

• 了解 Elastic 平台提供的 AI 驱动功能
• 探索 Agent Builder，了解如何使用 Elasticsearch 构建自定义 AI Agent