SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台elasticsearch-mcp-server

elasticsearch-mcp-server

elasticsearch-mcp-server 是一个基于 Model Context Protocol（MCP）的服务器实现，用于与 Elasticsearch 和 OpenSearch 进行交互。通过一组工具，它支持搜索文档、分析索引以及管理集群。该项目由 cr7258 开发并开源在 GitHub 上。

访问官网

工具介绍

Elasticsearch/OpenSearch MCP Server 是一个 Model Context Protocol（MCP）服务器实现，提供与 Elasticsearch 和 OpenSearch 的交互能力。该服务器通过一组工具使模型能够搜索文档、分析索引并管理集群。

主要能力

项目提供以下类别的工具：

通用操作：

  • general_api_request：执行通用 HTTP API 请求，适用于没有专用工具的 Elasticsearch/OpenSearch API。

索引操作：

  • list_indices：列出所有索引
  • get_index：返回一个或多个索引的信息（映射、设置、别名）
  • create_index：创建新索引
  • delete_index：删除索引
  • create_data_stream：创建新的数据流（需要匹配的索引模板）
  • get_data_stream：获取一个或多个数据流的信息
  • delete_data_stream：删除一个或多个数据流及其后备索引

文档操作：

  • search_documents：搜索文档
  • index_document：在索引中创建或更新文档
  • get_document：按 ID 获取文档
  • delete_document：按 ID 删除文档
  • delete_by_query：删除与查询匹配的文档

集群操作：

  • get_cluster_health：返回集群健康状况的基本信息
  • get_cluster_stats：返回集群统计信息的高层概览

别名操作：

  • list_aliases：列出所有别名
  • get_alias：获取特定索引的别名信息
  • put_alias：为特定索引创建或更新别名
  • delete_alias：删除特定索引的别名

分析器操作：

  • analyze_text：使用指定的分析器或自定义分析链分析文本，用于调试搜索查询和理解文本分词方式。

使用方式

环境变量配置

服务器支持以下环境变量：

基础认证（用户名/密码）：

  • ELASTICSEARCH_USERNAME：Elasticsearch 基础认证用户名
  • ELASTICSEARCH_PASSWORD：Elasticsearch 基础认证密码
  • OPENSEARCH_USERNAME：OpenSearch 基础认证用户名
  • OPENSEARCH_PASSWORD：OpenSearch 基础认证密码

API 密钥认证（仅 Elasticsearch，推荐）：

  • ELASTICSEARCH_API_KEY：Elasticsearch 或 Elastic Cloud 认证的 API 密钥

连接设置：

  • ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS：逗号分隔的主机列表（默认：https://localhost:9200）
  • ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS：用于命名集群配置的内联 JSON 对象。设置后，工具可通过可选的 cluster 参数定位特定集群
  • ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE：包含 clusters 对象的 JSON 文件路径。当配置嵌入在其他 JSON 文件（如 MCP 客户端配置）中时推荐使用，可避免 JSON 嵌套转义。同时设置时优先于内联变量
  • DEFAULT_CLUSTER：多集群配置下工具调用省略 cluster 时使用的默认集群名称（默认为第一个配置的集群）
  • VERIFY_CERTS：是否验证 SSL 证书（默认：false）
  • REQUEST_TIMEOUT：请求超时时间（秒，可选）

多集群配置

默认情况下，服务器使用来自 ELASTICSEARCH_HOSTS、ELASTICSEARCH_USERNAME、ELASTICSEARCH_PASSWORD 和 ELASTICSEARCH_API_KEY 的单个 Elasticsearch 集群，或来自 OPENSEARCH_HOSTS、OPENSEARCH_USERNAME 和 OPENSEARCH_PASSWORD 的单个 OpenSearch 集群。要配置多个命名集群，请将 ELASTICSEARCH_CLUSTERS（或 OPENSEARCH_CLUSTERS）设置为 MCP 服务器配置内的 JSON 对象。

为提升可读性，可将 ELASTICSEARCH_CLUSTERS_FILE（或 OPENSEARCH_CLUSTERS_FILE）指向独立的 JSON 文件，其值仅为路径，避免 JSON 嵌套转义。

每个工具都接受可选的 cluster 参数。省略时，服务器使用 DEFAULT_CLUSTER。未设置 DEFAULT_CLUSTER 时，使用 JSON 对象中的第一个集群作为默认值。

MCP 服务器认证（仅 HTTP 传输）

使用基于 HTTP 的传输（SSE 或 Streamable HTTP）运行 MCP 服务器时，可启用 Bearer 令牌认证以防止未授权访问。

  • MCP_API_KEY：MCP 服务器认证的 API 密钥。客户端必须包含 Authorization: Bearer <MCP_API_KEY> 头。

安全注意事项：

  • 认证仅适用于 HTTP 传输（sse、streamable-http）。stdio 传输使用本地进程通信，不需要认证。
  • 如果未设置 MCP_API_KEY，MCP 服务器将无需认证即可访问。通过网络暴露服务器时存在安全风险。
  • 对于使用 HTTP 传输的生产部署，请始终设置 MCP_API_KEY。

禁用高风险操作

  • DISABLE_HIGH_RISK_OPERATIONS：设为 true 可禁用所有写操作（默认：false）
  • DISABLE_OPERATIONS：逗号分隔的特定操作列表（可选，未设置时使用默认写操作列表）

当 DISABLE_HIGH_RISK_OPERATIONS 设为 true 时，所有执行写操作的 MCP 工具将从 MCP 客户端完全隐藏。此模式下默认禁用的 MCP 工具包括：

  • 索引操作：create_index、delete_index
  • 文档操作：index_document、delete_document、delete_by_query
  • 数据流操作：create_data_stream、delete_data_stream
  • 别名操作：put_alias、delete_alias
  • 通用 API 操作：general_api_request

也可以选择在 DISABLE_OPERATIONS 环境变量中指定逗号分隔的要禁用的操作列表。

GCF 响应编码（可选）

可选择将工具结果负载序列化为 GCF（Graph Compact Format），一种令牌优化的传输格式，用于模型读取的内容块。Elasticsearch 返回大量统一记录集（搜索命中、聚合桶、映射），GCF 最能压缩这种形式：在代表性响应上，相比紧凑 JSON 约减少 39% 的令牌（搜索命中约 40%），且无损。

structuredContent 保持不变，因此工具声明的输出模式仍然有效，任何非模型客户端仍接收 JSON；仅面向模型的文本块被重新编码。编码为故障安全：任何错误（包括值超出 GCF 规范的 int64 数值域，GCF 会拒绝而非静默近似）都会保留原始 JSON 结果不变，因此工具调用不会因编码而被丢弃。RESPONSE_FORMAT 未设置时默认行为不变。

复现令牌对比：uv run --with tiktoken python benchmarks/gcf_benchmark.py

启动 Elasticsearch/OpenSearch 集群

使用 Docker Compose 启动 Elasticsearch/OpenSearch 集群。 默认 Elasticsearch 用户名为 elastic，密码为 test123。默认 OpenSearch 用户名为 admin，密码为 admin。 可从 http://localhost:5601 访问 Kibana/OpenSearch Dashboards。

安装选项

选项 1：使用 uvx 使用 uvx 会自动从 PyPI 安装包，无需在本地克隆仓库。将以下配置添加到 Claude Desktop 的配置文件 claude_desktop_config.json。

选项 2：使用 uv 进行本地开发 使用 uv 需要本地克隆仓库并指定源代码路径。将以下配置添加到 Claude Desktop 的配置文件 claude_desktop_config.json。

Streamable HTTP 方式也可用。

版本兼容性

MCP 服务器与 Elasticsearch 7.x、8.x 和 9.x 兼容。默认使用 Elasticsearch 8.x 客户端（无后缀）。

要使用 Elasticsearch 7.x 客户端，请运行 elasticsearch-mcp-server-es7 变体。对于 Elasticsearch 9.x，使用 elasticsearch-mcp-server-es9。

如果要在本地运行不同的 Elasticsearch 变体（如 7.x 或 9.x），只需更新 pyproject.toml 中的 elasticsearch 依赖版本，然后启动服务器。

Kubernetes 部署

Docker 镜像发布至 ghcr.io/cr7258/elasticsearch-mcp-server，Helm chart 作为 OCI 制品位于 oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server 仓库。完整安装说明、配置参考和使用示例请参阅 Helm chart README。

许可

本项目采用 Apache License Version 2.0 许可。

同类工具

查看分类