MCP Server Graylog

🚀 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 令牌

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

常见错误信息

错误	含义	解决方案
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 获取指南。 快速开始：

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

变更日志

请参阅 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 文件。

🔗 链接

• npm 包
• GitHub 仓库
• 问题跟踪器
• Model Context Protocol
• Graylog 文档

🙏 致谢

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

---

为 Claude Desktop 社区用心打造 ❤️

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