Elastic MCP (Kij48)

Elastic MCP Server（弹性MCP服务器）

一个模型上下文协议（MCP）服务器，提供对Elasticsearch的只读访问。该服务器旨在帮助您使用关联ID跨系统追踪和关联日志条目。

特点/功能

• 只读操作所有工具均设计为可安全、只读地访问Elasticsearch
• 关联ID搜索通过相关ID查找所有相关日志条目的主要工具
• PII 遮蔽（或 PII 脱敏）自动屏蔽敏感信息（身份证号、电子邮件、电话号码等）
• 自定义查询支持复杂的Elasticsearch查询DSL查询
• 指数管理列出索引并查看它们的映射关系
• 文档检索通过索引和ID获取特定文档

安装

1. 安装依赖项：

npm install

1. 创建一个 .env 基于文件的 .env.example：

cp .env.example .env

1. 在（相应位置）配置您的Elasticsearch连接 .env：

ELASTICSEARCH_NODE=https://localhost:9200
ELASTICSEARCH_API_KEY=your_api_key_here

# OR use username/password
# ELASTICSEARCH_USERNAME=elastic
# ELASTICSEARCH_PASSWORD=your_password_here

# Optional configurations
ELASTICSEARCH_INDEX_PATTERN=logs-*
CORRELATION_ID_FIELD=correlation_id

配置

环境变量

连接设置：

• ELASTICSEARCH_NODEElasticsearch 端点 URL（必填）
• ELASTICSEARCH_API_KEY认证用的API密钥（可选，使用此密钥或用户名/密码）
• ELASTICSEARCH_USERNAME基本认证的用户名（可选）
• ELASTICSEARCH_PASSWORD基本认证的密码（可选）
• ELASTICSEARCH_INDEX_PATTERN默认搜索的索引模式（默认： logs-*)
• CORRELATION_ID_FIELD包含相关ID的字段名（默认： correlation_id）

PII（个人身份信息）掩码设置：

• PII_MASKING_ENABLED启用PII（个人可识别信息）遮蔽（默认： false，设置为 true （使）能够
• PII_MASK_CPR将丹麦的心肺复苏（CPR）号码格式化为XXXXXX-XXXX（默认： true （当启用遮罩时）
• PII_MASK_EMAIL隐藏电子邮件地址（默认： true （当启用遮罩时）
• PII_MASK_PHONE屏蔽电话号码（默认： true （当启用遮罩时）
• PII_MASK_CREDIT_CARD屏蔽信用卡号码（默认： true （当启用遮罩时）
• PII_MASK_SSN掩码社会保险号（默认： true （当启用遮罩时）

使用方法

运行服务器

直接启动服务器：

npm start

或者在开发时使用监视模式：

npm run dev

使用Claude Desktop进行配置

将此配置添加到您的Claude桌面配置文件中：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["C:\\repos\\MCP\\ElasticMcp\\index.js"],
      "env": {
        "ELASTICSEARCH_NODE": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key_here"
      }
    }
  }
}

或者，如果你有一个 .env 文件已配置，您可以使用：

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["C:\\repos\\MCP\\ElasticMcp\\index.js"]
    }
  }
}

可用工具

1. 按关联ID搜索

搜索与某个相关联ID相关的所有条目。这是在您的系统中追踪请求的主要工具。

参数：

• correlation_id （必填）：要搜索的相关联ID
• index_pattern （可选）：要搜索的索引模式（默认为配置的模式）
• size （可选）：最大结果数量（默认：100）
• sort_field （可选）：按哪个字段排序（默认：@timestamp）
• sort_order （可选）：排序顺序，"asc"（升序）或 "desc"（降序）（默认：asc）

示例：

{
  "correlation_id": "abc-123-def-456",
  "index_pattern": "logs-2024-*",
  "size": 50,
  "sort_order": "asc"
}

2. 获取文档

通过索引和ID检索特定文档。

参数：

• index （必填）：索引名称
• document_id （必填）：文档ID

示例：

{
  "index": "logs-2024-01-15",
  "document_id": "abc123xyz"
}

3. 自定义搜索

使用查询领域特定语言 (Query DSL) 执行自定义的 Elasticsearch 查询，以进行复杂搜索。

参数：

• query_dsl (必需): Elasticsearch 查询 DSL 对象
• index_pattern （可选）：要搜索的索引模式
• size （可选）：最大结果数量（默认：100）

示例：

{
  "index_pattern": "logs-*",
  "query_dsl": {
    "query": {
      "bool": {
        "must": [
          { "match": { "service.name": "api-gateway" }},
          { "range": { "@timestamp": { "gte": "now-1h" }}}
        ]
      }
    }
  },
  "size": 100
}

4. 列索引（或 列指标）

列出可用的Elasticsearch索引及其健康状态和文档数量。

参数：

• pattern （可选）：用于过滤的索引模式（默认：\*）

示例：

{
  "pattern": "logs-*"
}

5. 获取索引映射

获取索引的字段映射以了解其结构。

参数：

• index （必填）：索引名称或模式

示例：

{
  "index": "logs-2024-01-15"
}

用例

在您的系统中追踪请求

使用 search_by_correlation_id 用于查找与特定请求相关的所有日志条目的工具：

Find all logs for correlation ID "req-abc-123"

这将返回所有共享此关联ID的服务中的所有日志条目，并按时间顺序排序。

调试服务问题

1. 使用 list_indices 查看可用的日志索引
2. 使用 custom_search 查找特定服务的错误日志
3. 从错误中提取相关ID
4. 使用 search_by_correlation_id 获取完整的请求追踪信息

分析请求流量

按相关ID搜索，并按时间戳升序排序，以查看请求在您的微服务架构中的时间顺序流程。

PII 遮蔽（或 PII 脱敏）

该服务器内置了PII（个人可识别信息）屏蔽功能，以保护日志条目中的敏感数据。

它是如何工作的

当启用个人身份信息（PII）屏蔽功能时，服务器会在返回结果之前自动隐藏敏感信息。这一过程发生在从Elasticsearch检索数据之后，但发送到客户端之前。

支持的PII类型

1. 丹麦的CPR号码（或“个人识别码”） (PII_MASK_CPR）

- 格式：XXXXXX-XXXX（6位数字，可选连字符，后接4位数字） - 伪装成： ******-**** - 示例： 123456-7890 → ******-****

1. 电子邮件地址 (PII_MASK_EMAIL)

- 部分遮挡以保留上下文 - 示例： john.doe@example.com → jo***@example.com

1. 电话号码 (PII_MASK_PHONE)

- 丹麦及国际格式 - 伪装成： ** ** ** ** - 示例： +45 12 34 56 78 → ** ** ** **

1. 信用卡号码 (PII_MASK_CREDIT_CARD）

- 伪装成： **** **** **** ****

1. 社会保险号（或：社会安全号码） (PII_MASK_SSN）

- 美国社会保障号（SSN）格式 - 伪装成： ***-**-****

配置示例

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["C:\\repos\\MCP\\ElasticMcp\\index.js"],
      "env": {
        "ELASTICSEARCH_NODE": "https://your-cluster.es.cloud.com:9243",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "PII_MASKING_ENABLED": "true",
        "PII_MASK_CPR": "true",
        "PII_MASK_EMAIL": "true"
      }
    }
  }
}

选择性遮罩

您可以全局启用遮罩，但禁用特定类型：

PII_MASKING_ENABLED=true
PII_MASK_CPR=true
PII_MASK_EMAIL=false    # Don't mask emails
PII_MASK_PHONE=true

安全

此服务器仅支持只读操作：

• 未创建或更新任何文档
• 未进行索引修改
• 没有文档删除操作
• 没有集群配置更改

所有操作仅使用Elasticsearch的读取API（search， get， cat.indices， indices.getMapping）。

额外的安全功能

• PII（个人可识别信息）掩码处理在返回结果前自动删除敏感个人信息
• 只读角色支持与Elasticsearch只读API密钥配合使用
• 无数据修改所有工具均严格进行只读操作

故障排除

连接问题

如果你看到“无法连接到Elasticsearch”：

1. 验证您的 ELASTICSEARCH_NODE 是正确的
2. 检查您的身份验证凭据
3. 确保 Elasticsearch 正在运行且可访问
4. 检查防火墙/网络设置

证书错误

服务器已配置为 rejectUnauthorized: false 用于开发。在生产环境中，您应该：

1. 使用合适的SSL证书
2. 设定 rejectUnauthorized: true 在 config.js 中
3. 如需提供，请提供CA证书

未找到结果

如果搜索未返回任何结果：

1. 验证您的索引模式与您的索引相匹配
2. 检查一下 CORRELATION_ID_FIELD 配置与您的日志字段名称匹配
3. 使用 list_indices 验证索引是否存在
4. 使用 get_index_mapping 验证字段名称

许可证

麻省理工学院（MIT）