Elasticsearch

Elasticsearch MCP 服务

增强型 Elasticsearch MCP 服务解决方案——专注于安全与威胁分析

这是由 TocharianOU 维护的专业安全解决方案。它支持与所有 Elasticsearch API 全面交互，专为安全分析、威胁检测和事件调查而优化。功能包括高级安全监控、异常检测、威胁搜寻、根因分析和全面审计。

主要安全功能：

• 实时威胁检测和安全监控
• 用于异常检测的高级机器学习
• 根因分析和攻击链跟踪
• 安全事件调查和取证
• 合规性监控和审计报告

---

注意： 此解决方案面向安全专业人员、SOC 团队和威胁分析师。

使用模型上下文协议（MCP），即可通过任意 MCP 客户端（例如 Claude Desktop）直接连接到 Elasticsearch 数据。通过自然语言查询与 Elasticsearch 安全数据交互，开展高级威胁分析和事件响应。

先决条件

• Elasticsearch 实例
• Elasticsearch 身份验证凭据（API 密钥或用户名/密码）
• MCP 客户端（例如 Claude Desktop）或用于远程访问的 HTTP 客户端

多版本 Elasticsearch 支持

自动支持 Elasticsearch 5.x - 9.x，并可智能检测版本：

Version	Status	Client	Notes
ES 5.x	✅	5.6.22	EOL - 仅提供基本工具
ES 6.x	✅	6.8.8	EOL - 提供 ILM（6.6+）
ES 7.x	✅	7.17.14	LTS - 完整功能
ES 8.x	✅	8.19.1	推荐 - 最新功能、ES|QL（8.11+）
ES 9.x+	✅	Auto-fallback	面向未来

主要功能：

• 自动版本检测 - 无需手动配置
• 智能客户端选择 - 为你的 ES 版本加载合适的客户端
• 自适应功能 - 禁用不受支持的工具（例如，ES < 7.9 时禁用 Data Streams，ES < 8.11 时禁用 ES|QL）
• 特定版本优化 - 透明处理 API 差异

运行方式：

Connect → Detect ES version → Load matching client → Register compatible tools

查询护栏（v0.9.0）

从 v0.9.0 开始，服务附带一个查询护栏：位于 AI 模型与集群之间的确定性层。其设计理念很简单：

模型负责引导；护栏负责了解。 意图（“查找按用户划分的登录失败记录”）由模型负责。 正确性（真实字段名称、是否可聚合、版本差异）由护栏负责。

这在实践中意味着什么——这里介绍的是原则，而非内部实现：

• 实时事实优于随附知识，随附知识优于模型记忆。 每个查询在运行前都会根据集群的实际字段能力进行检查。随附的 ECS（Elastic Common Schema）词汇表提供含义；实时集群则提供存在性。绝不信任模型自己的记忆。
• 明确无误的错误会被静默修正；有歧义的错误则会转化为指导。 典型示例：现代 ECS 映射中多余的 .keyword 后缀会被自动修正（并报告修正情况）；未知字段会阻止注定失败的查询，并返回最接近的真实字段，而不是提供方错误。
• 字段知识不会占用上下文窗口。 完整的 ECS 字典（包含数千个字段）保存在进程内存中。模型仅通过 lookup_fields 按需检索所需的少量字段。
• 每个错误都必须可采取行动。 原始 Elasticsearch 错误会被改写，并附上实时建议和索引命名提示（数据流与旧版 Beats 命名、应通过 Kibana API 访问的内部索引等）。
• 模型无需了解任何版本信息。 命名时期、API 差异和映射风格差异（旧版 text + .keyword 子字段与现代裸 keyword）都由护栏完全处理。同一个模型在 ES 5.6 和 ES 9.x 上的行为完全一致——这已通过涵盖九个重要版本（5.6 → 9.0）的版本测试矩阵验证。
• 始终提供绕过途径。 当模型更清楚情况时，可按调用绕过验证（skip_lint）——例如，查询之外定义的运行时字段。护栏会提供协助；绝不会将模型困住。

SSL/TLS 连接

若要使用自签名证书或在测试环境中连接 Elasticsearch，可以设置以下环境变量：

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ 这会禁用 Node.js SSL 证书验证。仅在开发或测试环境中使用。生产环境中请始终使用受信任的 CA 证书。

安装与设置

安装（或运行）服务，通过环境变量将其指向你的集群，在 MCP 客户端中注册它，然后开始对话即可——服务会连接集群，并注册你的 ES 版本所支持的工具。

配置选项

Elasticsearch MCP Server 支持以下配置选项：

Elasticsearch 配置

环境变量	描述	必填
ES_URL	你的 Elasticsearch 实例 URL	是
ES_API_KEY	用于身份验证的 Elasticsearch API 密钥	否
ES_USERNAME	用于基本身份验证的 Elasticsearch 用户名	否
ES_PASSWORD	用于基本身份验证的 Elasticsearch 密码	否
ES_CA_CERT	Elasticsearch SSL/TLS 自定义 CA 证书的路径	否
NODE_TLS_REJECT_UNAUTHORIZED	设置为 0 以禁用 SSL 证书验证	否

传输模式配置（v0.3.0 新增）

环境变量	说明	默认值	取值
MCP_TRANSPORT	传输模式选择	stdio	stdio、http
MCP_HTTP_PORT	HTTP 服务端口（使用 HTTP 传输时）	3000	1-65535
MCP_HTTP_HOST	HTTP 服务主机（使用 HTTP 传输时）	localhost	任意有效主机

传输模式详情：

• Stdio 模式（默认）：适用于 Claude Desktop 和本地 MCP 客户端
• HTTP Streamable 模式：作为独立 HTTP 服务运行，支持远程访问、API 集成和 Web 应用

快速开始

选项 1：NPM 安装（推荐）

1. 通过 NPM 全局安装

   npm install -g @tocharianou/elasticsearch-mcp
   

2. 直接运行

   npx @tocharianou/elasticsearch-mcp
   

选项 2：GitHub Release（独立软件包）

1. 下载 Release 软件包

   • 前往 GitHub Releases
   • 下载最新的 .tar.gz 文件及其校验和文件（.sha256 和 .sha512）

2. 验证软件包完整性

   shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256
   # Should output: elasticsearch-mcp-v*.tar.gz: OK
   

3. 解压并使用

   mkdir elasticsearch-mcp && cd elasticsearch-mcp
   tar -xzf ../elasticsearch-mcp-v*.tar.gz
   
   # Run with your Elasticsearch credentials
   ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js
   

选项 3：从源码安装

1. 克隆仓库

   git clone https://github.com/TocharianOU/elasticsearch-mcp.git
   cd elasticsearch-mcp
   

2. 安装依赖项

   npm install
   

3. 构建项目

   npm run build
   

4. 配置 Claude Desktop 应用

   • 打开 Claude Desktop 应用
   • 前往 设置 > 开发者 > MCP 服务
   • 点击 Edit Config，并使用以下配置添加一个新的 MCP 服务：

   NPM 安装方式：

   {
     "mcpServers": {
       "elasticsearch-mcp-server": {
         "command": "npx",
         "args": [
           "@tocharianou/elasticsearch-mcp"
         ],
         "env": {
           "ES_URL": "your-elasticsearch-url",
           "ES_USERNAME": "elastic",
           "ES_PASSWORD": "your_pass",
           "NODE_TLS_REJECT_UNAUTHORIZED": "0"
         }
       }
     }
   }
   

   源码安装方式：

   {
     "mcpServers": {
       "elasticsearch-mcp-server-local": {
         "command": "node",
         "args": [
           "/path/to/your/elasticsearch-mcp/dist/index.js"
         ],
         "env": {
           "ES_URL": "your-elasticsearch-url",
           "ES_USERNAME": "elastic",
           "ES_PASSWORD": "your_pass",
           "NODE_TLS_REJECT_UNAUTHORIZED": "0"
         }
       }
     }
   }
   

5. 使用 MCP Inspector 调试（可选）

   ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector
   

安装与集成说明

如果 npm install -g 行为异常：

• 全局安装时出现权限错误（EACCES） — 不要使用 sudo。可以完全跳过全局安装，让 MCP 客户端运行 npx @tocharianou/elasticsearch-mcp （npx 会按需获取软件包），或者设置用户级前缀： npm config set prefix ~/.npm-global，并将其添加到 PATH。
• 注册表速度慢或访问受阻 — 仅在安装时使用镜像： npm install -g @tocharianou/elasticsearch-mcp --registry=https://registry.npmmirror.com。
• Node 版本 — 需要 Node 18+（node --version）。较旧的 Node 会在启动时因 ESM/fetch 错误而失败，而非在安装时失败。
• npx 冷启动 — 首次运行 npx 时会下载软件包；如果 MCP 客户端在首次连接时超时，请先在终端中运行一次 npx @tocharianou/elasticsearch-mcp 以预热缓存，然后重新连接。
• 完全离线的主机 — 使用 GitHub Release tarball（选项 2），并将客户端指向 node /path/to/dist/index.js；运行时不会获取任何内容。

Claude Desktop — 前往“设置” →“开发者” →“MCP 服务” →“Edit Config”，然后添加上方显示的 JSON 块。编辑后重启应用；该服务将显示在新对话的工具列表中。

Claude Code（CLI） — 按项目或全局注册该服务：

claude mcp add elasticsearch \
  -e ES_URL=https://your-es:9200 -e ES_API_KEY=your-key \
  -- npx @tocharianou/elasticsearch-mcp

任何其他 MCP 客户端 / 平台集成 — 以 HTTP 模式运行（MCP_TRANSPORT=http，见下文），并将客户端指向 http://host:port/mcp； 这是容器化平台的推荐配置，即每个集群连接使用一个服务实例。

凭据安全 — 环境变量会以明文形式写入客户端的配置文件。建议使用范围受限的只读 API 密钥（见下文的 Elasticsearch 访问控制），而非超级用户凭据。

方法 3：HTTP Streamable 模式（v0.3.0 新增）

将服务作为独立的 HTTP 服务运行，以便远程访问和 API 集成：

# Start HTTP server (default port 3000)
MCP_TRANSPORT=http \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

# Or with custom port and host
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

HTTP Streamable 模式功能：

• 在 http://host:port/mcp 端点提供 MCP 服务
• 可通过 http://host:port/health 进行运行状况检查
• 基于会话的连接管理
• 支持 POST（JSON-RPC 请求）和 GET（SSE 流）
• 兼容任何 HTTP 客户端或 MCP SDK

任何支持 MCP 的客户端（或通过 HTTP 传输普通 JSON-RPC 的客户端）都可以与 /mcp 端点通信：初始化一次，并在后续的 tools/list / tools/call 请求中保留返回的 mcp-session-id 标头。使用 /health 进行存活检查。

可用工具

工具	描述	最低版本
list_indices	按模式筛选、健康状态筛选、排序并生成令牌感知摘要，列出索引	ES 5.x+
get_mappings	获取字段映射，支持平面／树形／原始模式、字段筛选和多索引比较	ES 5.x+
es_search	完整的 Query DSL 搜索，支持自动高亮，以及 harness 字段验证／自动修复	ES 5.x+
lookup_fields	查找正确的字段名称：将 ECS 词汇与索引的实际字段取交集	ES 5.x+
execute_es_api	直接执行任意 ES REST 端点（GET/POST/PUT/DELETE/HEAD）	ES 5.x+
get_shards	提供分片信息、健康状态分析、问题检测和建议	ES 5.x+
list_data_streams	列出并分析数据流，提供 ILM 信息和后备索引详情	ES 7.9+
esql_query	执行基于管道的 ES|QL 查询，并进行 harness 字段验证和表格化输出	ES 8.11+

启动时会自动跳过集群版本不支持的工具。 es_search 和 esql_query 可接受 skip_lint: true，以跳过 harness 验证，处理边缘情况（例如，在查询外定义的运行时字段）。

ES|QL 查询工具（esql_query）

ES|QL 是 Elasticsearch 的现代管道式查询语言，无需复杂的 JSON DSL，即可轻松进行分析和数据探索。

查询示例：

FROM logs-* | WHERE level == "error" | STATS count = COUNT(*) BY service | SORT count DESC | LIMIT 20
FROM metrics-* | WHERE @timestamp > NOW() - 1 hour | STATS avg_cpu = AVG(cpu.usage) BY host.name
FROM auditbeat-* | WHERE event.action == "user_login" AND event.outcome == "failure" | LIMIT 50

参数：

• query — ES|QL 字符串（必需）
• params — 用于替换 ? 占位符的位置参数（可选）
• include_types — 在输出中包含列类型信息（可选，默认值为 false）
• break_token_rule — 绕过大结果集的令牌限制（可选，默认值为 false）
• skip_lint — 绕过 harness 字段验证（可选，默认值为 false）

仅在 ES 8.11+ 集群上自动注册。

参与贡献

欢迎社区成员参与贡献！有关如何贡献的详情，请参阅贡献指南。

工作原理

1. MCP 客户端（AI 模型）决定要查找什么，并调用工具。
2. harness 根据实时集群验证请求——对明确无误的内容进行修正，阻止可能失败的请求，并将错误转换为指导信息。
3. 返回的结果受令牌数量限制且已预先整理（包含高亮内容、表格和聚合摘要），因此长时间的调查也能保持在上下文限制内。

安全分析示例

提示

以下是可通过 MCP 客户端尝试的安全分析查询。

威胁检测：

• “分析过去 24 小时内的暴力破解攻击尝试”
• “检测系统中的异常登录行为和可疑 IP 地址”
• “识别潜在的 SQL 注入攻击模式和恶意请求”
• “发现网络流量中的 DDoS 攻击特征和流量异常”

根因分析：

• “追踪特定安全事件的完整攻击链和影响范围”
• “分析系统故障的根本原因和传播路径”
• “识别数据泄露源头及涉及的敏感信息”
• “调查用户权限滥用事件，包括时间线和操作记录”

威胁情报：

• “创建机器学习模型，以检测零日攻击和未知威胁”
• “建立行为基线，并识别偏离正常模式的活动”
• “分析恶意域名和 IP 地址的威胁等级及攻击历史”
• “检测高级持续性威胁（APT）的行为特征和攻击模式”

实时监控：

• “监控当前系统中的活动威胁和正在进行的攻击”
• “检测异常数据访问模式和权限提升行为”
• “发现可疑网络通信和数据外泄活动”
• “识别系统资源消耗异常和性能下降的安全原因”

安全最佳实践

警告

避免使用 cluster-admin 权限。创建权限范围受限的专用 API 密钥，并在索引级别应用精细化访问控制，以防止未授权的数据访问。

软件包完整性验证

下载发行版软件包时，务必验证校验和以确保完整性：

# Verify SHA256 checksum
shasum -a 256 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha256

# Verify SHA512 checksum
shasum -a 512 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha512

这有助于防范：

• 下载内容损坏
• 软件包被篡改
• 中间人攻击

Elasticsearch 访问控制

你可以创建权限最小化的专用 Elasticsearch API 密钥，以控制对数据的访问：

{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

许可证

本项目采用 Apache License 2.0 许可。

故障排除

• 确保 MCP 配置正确。
• 验证你的机器是否可以访问 Elasticsearch URL。
• 检查你的身份验证凭据（API 密钥或用户名/密码）是否具有所需权限。
• 如果使用带有自定义 CA 的 SSL/TLS，请确认证书路径正确且文件可读。
• 查看终端输出中的错误消息。

如果遇到问题，欢迎在 GitHub 仓库中提交 issue。