MCP Server Elasticsearch Sl

Elasticsearch MCP服务器

](https://www.npmjs.com/package/@tocharianou/elasticsearch-mcp) ](https://www.npmjs.com/package/@tocharianou/elasticsearch-mcp) 

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

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

主要安全功能：

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

______________________________________________________________________

注： 此解决方案需要有效的Elasticsearch许可证（试用版、白金版或企业版），专为安全专业人员、SOC团队和威胁分析师设计。

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

先决条件

• Elasticsearch实例
• 需要有效的Elasticsearch许可证（试用版、白金版、企业版）。
• Elasticsearch身份验证凭据（API密钥或用户名/密码）
• MCP客户端（如Claude Desktop）或用于远程访问的HTTP客户端

⚠️ 此项目要求您的Elasticsearch集群具有有效的许可证。如果您没有许可证，可以激活试用许可证，如下所示。

多版本Elasticsearch支持

自动支持Elasticsearch 5.x-9.x，具有智能版本检测功能：

主要特点：

• 自动版本检测 -无需手动配置
• 智能客户端选择 -为您的ES版本加载正确的客户端
• 自适应功能 -禁用不受支持的工具（例如，ES\ ⚠️ 这将禁用Node.js SSL证书验证。仅在开发或测试环境中使用。对于生产，始终使用受信任的CA证书。

安装和设置

1. 开启对话

- 在MCP客户端中打开新对话 - MCP服务器应自动连接 - 现在，您可以询问有关Elasticsearch数据的问题

配置选项

Elasticsearch MCP服务器支持以下配置选项：

Elasticsearch配置

传输模式配置（v0.3.0中的新功能）

运输方式详细信息：

• 标准模式 （默认）：适用于Claude Desktop和本地MCP客户端
• HTTP流模式：作为独立的HTTP服务器运行，用于远程访问、API集成和web应用程序

快速开始

选项1:NPM安装（推荐）

1. 通过NPM进行全局安装

   npm install -g @tocharianou/elasticsearch-mcp

1. 直接运行

   npx @tocharianou/elasticsearch-mcp

选项2:GitHub发布（独立包）

1. 下载发布包

- 首选 - 下载最新 .tar.gz 文件及其校验和文件(.sha256 和 .sha512)

1. 验证包完整性

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

1. 提取和使用

   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

1. 再进行

   npm install

1. 构建项目

   npm run build

1. 配置Claude桌面应用程序

- 打开 Claude桌面应用程序 - 首选 设置>开发人员>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"
         }
       }
     }
   }

1. 使用MCP检查器进行调试

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

这将启动MCP检查器，允许您调试和分析请求。您应该看到：

   Starting MCP inspector...
   Proxy server listening on port 3000

   MCP Inspector is up and running at http://localhost:5173

方法3:HTTP流模式（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流模式功能：

• 暴露MCP服务器 http://host:port/mcp 端点
• 健康检查可在 http://host:port/health
• 基于会话的连接管理
• 支持POST（JSON-RPC请求）和GET（SSE流）
• 与任何HTTP客户端或MCP SDK兼容

HTTP客户端使用示例：

// Initialize connection
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'my-client', version: '1.0.0' }
    },
    id: 1
  })
});

const sessionId = response.headers.get('mcp-session-id');

// Subsequent requests include session ID
const toolsResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/list',
    params: {},
    id: 2
  })
});

// Call a tool (e.g., list_indices)
const indicesResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'list_indices',
      arguments: {}
    },
    id: 3
  })
});

可用工具

启动时会自动跳过群集版本不支持的工具。

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)

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

贡献

我们欢迎社区的贡献！有关如何捐款的详细信息，请参阅 贡献指南.

运作原理

1. MCP客户端分析您的请求，并确定需要哪些Elasticsearch操作。
2. MCP服务器与ES通信。
3. MCP客户端处理结果，并以用户友好的格式呈现，包括亮点、汇总摘要和异常见解。

安全分析示例

\[！提示\] 以下是您可以使用MCP客户端尝试的以安全为重点的查询。

威胁检测：

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

根本原因分析：

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

威胁情报：

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

实时监控：

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

安全最佳实践

\[！警告\] 避免使用集群管理员权限。创建范围有限的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许可证2.0获得许可。

故障排除

• 确保您的MCP配置正确。
• 验证您的Elasticsearch URL是否可以从您的计算机访问。
• 请检查您的身份验证凭据（API密钥或用户名/密码）是否具有必要的权限。
• 如果将SSL/TLS与自定义CA一起使用，请验证证书路径是否正确以及文件是否可读。
• 查看终端输出中的错误消息。

如果您遇到问题，请随时在GitHub存储库上打开问题。

使用试用许可证运行

如果您的Elasticsearch集群没有有效的许可证，您可以使用以下命令激活30天试用许可证：

curl -X POST -u elastic:your_password \
  -k "https://your-es-host:9200/_license/start_trial?acknowledge=true"

• 替换 your_password 和 your-es-host 使用您的真实凭据和主机。
• 这将在30天内启用所有功能。

注： 如果您的集群没有有效的许可证（试用版、白金版、enterprice等），则此项目将不会启动。