金大哥 - mcp-server-graylog MCP 详情

article

README

🚀 mcp-server-graylog

mcp-server-graylog 是一款用于 Graylog 日志搜索的 Model Context Protocol (MCP) 服务器。借助它，你可以依据绝对或相对时间戳搜索日志，按流进行过滤，还能直接从 Claude Desktop 调试生产问题。

🚀 快速开始

本项目为生产调试而构建，可使用精确时间戳搜索 Graylog 日志，按应用流过滤，并获取用于排查生产问题的可行见解。

✨ 主要特性

✅ 绝对时间戳搜索：使用精确的时间范围调试特定错误。
✅ 相对时间戳搜索：搜索最近的日志（过去 N 秒）。
✅ 流发现：列出所有可用的流/应用程序。
✅ 系统健康检查：验证 Graylog 连接性。
✅ 全面验证：支持 ISO 8601 时间戳、查询语法、流 ID。
✅ 清晰的错误消息：针对身份验证、网络和 API 问题提供可操作的错误信息。
✅ 超时处理：30 秒超时设置，防止请求挂起。
✅ 生产就绪：通过 54 项测试，代码质量评分为 9.2/10。

📦 安装指南

选项 1：使用 npx（推荐）

# 无需安装 - 直接使用 npx
npx mcp-server-graylog

选项 2：全局安装

npm install -g mcp-server-graylog

选项 3：本地安装

# 克隆仓库
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

# 安装依赖
npm install

💻 使用示例

可用工具

1. search_logs_absolute

使用绝对时间戳（从/到）搜索日志。非常适合调试具有特定时间戳的错误，这些时间戳可来自监控工具或错误跟踪系统。参数：

query（必需）：使用 Elasticsearch 语法的搜索查询。
from（必需）：ISO 8601 格式的开始时间戳。
to（必需）：ISO 8601 格式的结束时间戳。
streamId（可选）：用于过滤结果的流 ID。
limit（可选）：最大结果数（默认值：50，最大值：1000）。

示例：

{
  "query": "\"/api/v1/registrations\" AND \"PUT\"",
  "from": "2025-10-23T10:00:00.000Z",
  "to": "2025-10-23T11:00:00.000Z",
  "streamId": "646221a5bd29672a6f0246d8",
  "limit": 100
}

2. search_logs_relative

使用相对时间范围（例如，过去 15 分钟）搜索日志。适用于最近的日志分析。参数：

query（必需）：使用 Elasticsearch 语法的搜索查询。
rangeSeconds（可选）：以秒为单位的时间范围（默认值：900 = 15 分钟，最大值：86400 = 24 小时）。
streamId（可选）：用于过滤结果的流 ID。
limit（可选）：最大结果数（默认值：50，最大值：1000）。

示例：

{
  "query": "level:ERROR",
  "rangeSeconds": 3600,
  "limit": 100
}

3. list_streams

列出所有可用的 Graylog 流（应用程序）。用于发现用于过滤的流 ID。参数：无 返回值：

{
  "total": 3,
  "streams": [
    {
      "id": "646221a5bd29672a6f0246d8",
      "title": "clientmaster",
      "description": "Client Master application logs",
      "disabled": false
    }
  ]
}

4. get_system_info

获取 Graylog 系统信息和健康状态。验证连接性并检查服务器版本。参数：无 返回值：

{
  "version": "5.1.0",
  "codename": "graylog",
  "cluster_id": "abc123",
  "is_processing": true,
  "timezone": "UTC"
}

查询示例

搜索错误

level:ERROR

搜索特定端点

"/api/v1/registrations" AND "PUT"

搜索 HTTP 状态码

status:500
status:>=400

搜索用户操作

user_id:12345 AND action:login

搜索慢请求

duration_ms:>1000

搜索异常

exception:NullPointerException

组合多个条件

level:ERROR AND source:nexus AND message:*timeout*

使用通配符搜索

message:*connection refused*

按字段存在性搜索

_exists_:error_code

常见用例

1. 调试生产错误

当从监控系统获得带有时间戳的错误时：

1. 从监控工具复制错误时间戳。
2. 使用 search_logs_absolute 并设置 ±5 分钟的时间窗口。
3. 按应用程序流过滤。
4. 在日志中查找根本原因。

2. 监控最近的部署

部署后：

1. 使用 search_logs_relative 搜索过去 15 分钟的日志。
2. 搜索 level:ERROR。
3. 验证是否未引入新错误。

3. 调查 API 故障

当 API 端点失败时：

1. 搜索端点路径："/api/v1/endpoint"。
2. 按状态码过滤：status:>=400。
3. 检查错误模式。

📚 详细文档

配置

Claude Desktop 设置

将以下内容添加到你的 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

使用 npx（推荐）

{
  "mcpServers": {
    "graylog": {
      "command": "npx",
      "args": ["-y", "mcp-server-graylog"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

使用本地安装

{
  "mcpServers": {
    "graylog": {
      "command": "node",
      "args": ["/path/to/mcp-server-graylog/src/index.js"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

环境变量

| 变量 | 是否必需 | 描述 | |------|----------|-------------| | BASE_URL | 是 | Graylog 服务器 URL（例如，https://graylog.example.com） | | API_TOKEN | 是 | Graylog API 令牌（基本身份验证的用户名，密码为 "token"） |

获取 Graylog API 令牌

登录到 Graylog 网页界面。
转到 System → Users。
选择你的用户。
点击 Edit tokens。
创建一个具有读取权限的新令牌。
复制令牌值。

常见错误信息

| 错误 | 含义 | 解决方案 | |-------|---------|----------| | Authentication failed | API 令牌无效 | 检查配置中的 API_TOKEN | | Invalid query | Elasticsearch 语法错误 | 检查查询语法和参数 | | Endpoint not found | Graylog URL 错误 | 检查配置中的 BASE_URL | | Cannot reach Graylog | 网络连接问题 | 验证 Graylog 是否可访问 | | Invalid timestamp | 时间戳格式错误 | 使用 ISO 8601 格式（例如，2025-10-23T10:00:00.000Z） |

故障排除

服务器无法启动

检查环境变量：

# 验证 BASE_URL 和 API_TOKEN 是否在 Claude Desktop 配置中设置
# 检查 Claude Desktop 日志：
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log

验证 Graylog 可访问性：

curl -u "YOUR_API_TOKEN:token" https://graylog.example.com/api/system

身份验证错误

验证 API 令牌在 Graylog 中具有读取权限。
令牌格式：使用令牌值作为用户名，"token" 作为密码。
检查令牌是否未过期。

未返回结果

使用 list_streams 工具验证流 ID 是否正确。
检查时间戳范围是否包含数据。
尝试将查询简化为 * 以查看是否存在任何数据。
验证流是否未禁用。

集成测试失败

# 设置集成测试的环境变量
export INTEGRATION_TESTS=true
export BASE_URL=https://graylog.example.com
export API_TOKEN=your_token_here

# 运行集成测试
npm run test:integration

开发

前提条件

Node.js >= 18.0.0
npm >= 8.0.0
访问 Graylog 实例（用于集成测试）

开发工作流程

# 安装依赖
npm install

# 在开发模式下运行（自动重新加载）
npm run dev

# 运行测试
npm test

# 在监视模式下运行测试
npm run test:watch

# 仅运行单元测试
npm run test:unit

# 运行集成测试（需要 Graylog 实例）
INTEGRATION_TESTS=true BASE_URL=https://graylog.example.com API_TOKEN=xxx npm run test:integration

# 检查语法
npm run lint

项目结构

mcp-server-graylog/
├── src/
│   └── index.js           # 主服务器实现（429 行）
├── test/
│   ├── helpers.test.js    # 辅助函数测试（14 项测试）
│   ├── validation.test.js # 输入验证测试（24 项测试）
│   ├── mcp-protocol.test.js # MCP 协议测试（16 项测试）
│   └── integration.test.js  # 集成测试（7 项测试）
├── example-config.json    # Claude Desktop 配置示例
├── CONTRIBUTING.md        # 贡献指南
├── CHANGELOG.md          # 版本历史
└── package.json         # npm 配置

运行测试

# 运行所有测试（54 项测试）
npm test

# 预期输出：
# tests 54
# pass 54
# fail 0

架构

简单、专注的架构，仅在一个文件中（429 行）：

配置与验证：检查环境变量。
辅助函数：ISO 8601 验证、错误格式化。
MCP 服务器设置：标准 MCP 协议实现。
工具定义：4 个工具，具有清晰的架构。
工具实现：干净、经过验证的函数。
服务器启动：验证后连接。

设计原则：

✓ 简单且易于维护
✓ 单文件，易于理解
✓ 关注点清晰分离
✓ 全面的错误处理
✓ 边界处的输入验证
✓ 一致的响应格式

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。 快速开始：

分叉仓库。
创建功能分支。
为你的更改添加测试。
确保所有测试通过（npm test）。
提交拉取请求。

变更日志

请参阅 CHANGELOG.md 了解版本历史和发布说明。

安全

使用环境变量存储敏感数据（绝不硬编码）。
正确实现基本身份验证。
输入验证可防止注入攻击。
超时设置可防止挂起请求。
错误消息不会泄露敏感信息。

若要报告安全漏洞，请在 GitHub 上创建私人安全建议。

🔧 技术细节

本项目采用简单且专注的架构，核心代码集中在一个文件（src/index.js，共 429 行）中实现。主要包含以下几个部分：

配置与验证：对环境变量进行检查，确保服务器启动时所需的配置信息正确无误。
辅助函数：提供 ISO 8601 时间戳验证、错误格式化等功能，增强代码的复用性和可维护性。
MCP 服务器设置：按照标准的 MCP 协议进行服务器的初始化和配置，确保与其他系统的兼容性。
工具定义：明确了 4 个工具（search_logs_absolute、search_logs_relative、list_streams、get_system_info）的输入输出模式，使得各个工具的功能和使用方式清晰明了。
工具实现：针对每个工具编写了具体的实现函数，这些函数经过严格的验证和测试，保证了功能的正确性和稳定性。
服务器启动：在启动服务器之前，会对配置信息进行验证，验证通过后才会建立与 Graylog 的连接。

这种架构设计遵循了简单和可维护的原则，将各个功能模块清晰地分离，便于开发者理解和扩展。同时，全面的错误处理机制和输入验证机制，提高了系统的健壮性和安全性。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🔗 链接

🙏 致谢

使用 @modelcontextprotocol/sdk 构建。
受 MCP 社区的启发。
感谢所有贡献者！

为 Claude Desktop 社区用心打造 ❤️

如有问题或需要支持，请在 GitHub 上创建问题