使用说明

mcp服务器灰色日志

用于Graylog日志搜索的模型上下文协议（MCP）服务器。通过绝对/相对时间戳搜索日志，按流过滤，并直接从Claude Desktop调试生产问题。

专为生产调试而设计 -使用精确的时间戳搜索Graylog日志，按应用程序流过滤，并获得可操作的见解，以排除生产问题。

特征

✅ 绝对时间戳搜索 -调试具有精确时间范围的特定错误
✅ 相对时间戳搜索 -搜索最近的日志（最近N秒）
✅ 分布式跟踪 -跟随a trace_id 所有服务
✅ 周围的日志上下文 -查看错误周围±N秒发生了什么
✅ 复合事件分析 -一个工具调用粉丝进行跟踪+上下文+基线
✅ 字段聚合 -按服务/级别/pod/lead_id和带宽高效投影进行组计数
✅ 流发现 -列出所有可用流/应用程序
✅ 系统健康检查 -验证Graylog连接
✅ 全面验证 -ISO 8601时间戳、查询语法、流ID
✅ 清除错误消息 -针对身份验证、网络和API问题的可操作错误
✅ 超时处理 -30秒超时防止挂起
✅ 生产就绪 -54次测试，9.2/10代码质量分数

安装

选项1：与npx一起使用（推荐）

# No installation needed - use directly with npx
npx mcp-server-graylog

选项2：全局安装

npm install -g mcp-server-graylog

选项3：本地安装

# Clone the repository
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

# Install dependencies
npm install

配置

Claude桌面设置

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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令牌（基本身份验证的用户名，密码为“令牌”）

获取您的Graylog API代币

登录Graylog网页界面
首选 系统→ Users
选择您的用户
点击 编辑令牌
创建具有读取权限的新令牌
复制令牌值

可用工具

1.搜索_绝对

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

参数：

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.搜索_日志_相关

使用相对时间范围搜索日志（例如，最近15分钟）。可用于最近的日志分析。

参数：

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

例子：

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

3.跟踪请求

使用 trace_id.从每个流中获取日志，按服务/pod分组，并按时间顺序对每个服务的消息进行排序。对于微服务架构中的分布式调试至关重要。

参数：

traceId （必填）：要遵循的跟踪ID（例如。， abbb27610a7fd76be8fb5af17edbe00d)
from （必填）：ISO 8601格式的开始时间戳（搜索窗口）
to （必填）：ISO 8601格式的结束时间戳（搜索窗口）
limit （可选）：最大结果（默认值：200，最大值：1000）

例子：

{
  "traceId": "abbb27610a7fd76be8fb5af17edbe00d",
  "from": "2026-05-13T15:38:00.000Z",
  "to":   "2026-05-13T15:48:00.000Z"
}

4.获取周围环境日志

在时间戳的±N秒内返回日志，可选择按源/吊舱/流进行过滤。显示错误前后发生的情况。

参数：

timestamp （必填）：ISO 8601格式的中心时间戳
source （可选）：要筛选的源主机名或pod
streamId （可选）：流ID过滤器
windowSeconds （可选）：每侧窗口（默认值：5，最大值：300）
limit （可选）：最大结果（默认值：100）

例子：

{
  "timestamp": "2026-05-13T15:43:27.844Z",
  "source": "argus-production-f747f5d4d-x9hpp",
  "windowSeconds": 10
}

5.事故分析

复合工具。 一个呼叫会分散到三个搜索，并返回一个聚合的事件报告——在调查特定跟踪时可以节省2-3个LLM编排轮。

内部执行：

完整的跟踪跳链(trace_id:X)
Pod在第一个错误/关键/致命跳跃周围查看周围日志（按以下条件筛选 pod: 避免共享主机上的多租户噪音）
锚点服务的尾随小时误差基线

参数：

traceId （必填）：要调查的跟踪ID
from （必填）：ISO 8601格式的开始时间戳
to （必填）：ISO 8601格式的结束时间戳
window （可选）：以秒为单位包围日志窗口（默认值：10，最大值：300）
baselineSeconds （可选）：基线查找的跟踪窗口（默认值：3600，最大值：86400）

例子：

{
  "traceId": "abbb27610a7fd76be8fb5af17edbe00d",
  "from": "2026-05-13T15:38:00.000Z",
  "to":   "2026-05-13T15:48:00.000Z",
  "window": 10,
  "baselineSeconds": 3600
}

退货（删节）：

{
  "trace_id": "abbb27610a7fd76be8fb5af17edbe00d",
  "found": true,
  "steps_executed": 4,
  "summary": {
    "hops": 4,
    "services_involved": ["argus"],
    "errors_in_trace": 1,
    "anchor_service": "argus",
    "anchor_pod": "argus-production-f747f5d4d-x9hpp",
    "first_error": { "timestamp": "...", "service": "argus", "message": "nil fund_id ...", "lead_id": "..." },
    "request": { "http_path": "/api/v2/user/graph", "http_method": "POST", "http_status": 200, "duration_ms": 67 },
    "baseline_errors_in_service": 16,
    "baseline_window_seconds": 3600
  },
  "trace_hops": [...],
  "surrounding_logs": [...]
}

6.聚合日志

计数按字段分组的日志条目——Graylog最常用的操作，进行了一次调用。发出一次搜索 fields=<group_field> 投影（因此只下载您想要的列）并在客户端聚合。替换Graylog 5.x删除的遗留术语聚合端点。

参数：

query （必填）：过滤器（Elasticsearch语法）。使用 * 对于所有条目。
field （必填）：分组依据的字段。常见： service, logger_level, pod, lead_id, http_status, container_name.
from+to 或 rangeSeconds （必填，互斥）：时间窗口
size （可选）：返回前N（默认值25，最大值100）。休息总结为 other.
fetchLimit （可选）：要聚合的最大消息数（默认值5000，最大值10000）。当匹配超过此值时， truncated: true 被标记。
streamId （可选）

例子：

{
  "query": "logger_level:error",
  "field": "service",
  "rangeSeconds": 1800,
  "size": 10
}

退货：

{
  "field": "service",
  "query": "logger_level:error",
  "time_range": "Last 1800 seconds",
  "total_matched": 30,
  "messages_aggregated": 30,
  "truncated": false,
  "unique_groups": 5,
  "top": { "milkyway": 8, "argus": 4, "telex": 4, "advisory": 3, "auth": 1 },
  "other": 0,
  "missing": 10,
  "api_calls": 1
}

这 missing count是与查询匹配但按字段分组没有值的消息，这是日志卫生问题的有用信号。

7.列表流

列出所有可用的Graylog流（应用程序）。使用此功能可发现用于筛选的流ID。

参数： 无

退货：

{
  "total": 3,
  "streams": [
    {
      "id": "646221a5bd29672a6f0246d8",
      "title": "application-api",
      "description": "API application logs",
      "disabled": false
    }
  ]
}

8.获取系统信息

获取Graylog系统信息和健康状态。验证连接并检查服务器版本。

参数： 无

退货：

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

技能和代理（v2.3.0+）

当作为Claude Code插件安装时，此软件包附带了教Claude的剧本当和怎么使用上述MCP工具。

技能

技能	何时触发	它的作用
`graylog`	“搜索日志”、“检查灰色日志”、一般日志问题	入口点。将常见问题映射到正确的工具，解释streams/trace_id/query语法，指出专业技能。
`trace-debugging`	“trace_id”、“跟踪此请求”、“分布式跟踪”	跨服务的单个请求调查。提取轨迹，查找错误跨度，收集周围的上下文，合成时间线。
`incident-triage`	“错误激增”、“停机”、“警报触发”	将活动事件本地化为服务+模式。按服务聚合错误，与前一个窗口进行基线比较，钻取最严重的违规者，检查部署相关性。
`troubleshooting`	Graylog工具故障（401，连接被拒绝，结果为空）	诊断连接、身份验证、查询语法。总是从开始 `get_system_info`.

代理

代理	何时发货	退货内容
`graylog-trace-analyzer`	跟踪调查预计会出现>200条记录行或跨度>5个服务	结构化的时间线（≤50个条目）加上起源、传播、根本原因行和2-4句判决。将原始日志保留在父上下文之外。

安装插件时自动加载技能。代理可以通过Claude Code的子代理机制进行调度 subagent_type: "graylog-trace-analyzer".

查询示例

搜索错误

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. Copy error timestamp from your monitoring tool
2. Use search_logs_absolute with ±5 minute window
3. Filter by application stream
4. Find root cause in logs

2.监控最近的部署

部署后：

1. Use search_logs_relative with last 15 minutes
2. Search for level:ERROR
3. Verify no new errors introduced

3.调查API故障

当API终结点失败时：

1. Search for endpoint path: "/api/v1/endpoint"
2. Filter by status codes: status:>=400
3. Check error patterns

错误消息

服务器提供清晰、可操作的错误消息：

错误	含义	解决方案
认证失败	无效的API令牌	检查 `API_TOKEN` 在配置中
无效查询	Elasticsearch语法错误	检查查询语法和参数
未找到终结点	Graylog URL错误	检查 `BASE_URL` 在配置中
无法联系到Graylog	网络连接问题	验证Graylog是否可访问
无效时间戳	错误的时间戳格式	使用ISO 8601格式（例如。， `2025-10-23T10:00:00.000Z`)

故障排除

服务器无法启动

检查环境变量：

# Verify BASE_URL and API_TOKEN are set in Claude Desktop config
# Check Claude Desktop logs:
# 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中是否具有读取权限
令牌格式：使用令牌值作为用户名，“令牌”作为密码
支票令牌尚未过期

未返回任何结果

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

集成测试失败

# Set environment variables for integration tests
export INTEGRATION_TESTS=true
export BASE_URL=https://graylog.example.com
export API_TOKEN=your_token_here

# Run integration tests
npm run test:integration

发展

先决条件

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

开发工作流程

# Install dependencies
npm install

# Run in development mode (auto-reload)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run only unit tests
npm run test:unit

# Run integration tests (requires Graylog instance)
INTEGRATION_TESTS=true BASE_URL=https://graylog.example.com API_TOKEN=xxx npm run test:integration

# Check syntax
npm run lint

项目结构

mcp-server-graylog/
├── src/
│   └── index.js           # Main server implementation (429 lines)
├── test/
│   ├── helpers.test.js    # Helper function tests (14 tests)
│   ├── validation.test.js # Input validation tests (24 tests)
│   ├── mcp-protocol.test.js # MCP protocol tests (16 tests)
│   └── integration.test.js  # Integration tests (7 tests)
├── example-config.json    # Claude Desktop config example
├── CONTRIBUTING.md        # Contributing guidelines
├── CHANGELOG.md          # Version history
└── package.json         # npm configuration

运行测试

# Run all tests (54 tests)
npm test

# Expected output:
# tests 54
# pass 54
# fail 0

建筑

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

配置与验证 -环境变量检查
Helper函数 -ISO 8601验证，错误格式化
MCP服务器设置 -标准MCP协议实施
工具定义 -4个具有清晰模式的工具
工具实施 -干净、经过验证的功能
服务器启动 -验证然后连接

设计原则：

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

贡献

欢迎投稿！请参阅贡献.md 作为指导方针。

快速入门：

分叉存储库
创建要素分支
为您的更改添加测试
确保所有测试通过(npm test)
提交拉取请求

更新日志

看更改日志.md 查看版本历史和发行说明。

安全

敏感数据的环境变量（从未硬编码）
正确实施基本身份验证
输入验证可防止注入攻击
超时可防止挂起请求
错误消息不会泄露敏感信息

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

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

链接

致谢

内置于 @模型上下文协议/sdk
受到MCP社区的启发
感谢所有贡献者！

由...制作❤️ 克劳德桌面社区

如有疑问或支持，请在GitHub上发布问题

使用说明

mcp服务器灰色日志

特征

目录

安装

选项1：与npx一起使用（推荐）

选项2：全局安装

选项3：本地安装

配置

Claude桌面设置

使用npx（推荐）

使用本地安装

环境变量

获取您的Graylog API代币

可用工具

1.搜索_绝对

2.搜索_日志_相关

3.跟踪请求

4.获取周围环境日志

5.事故分析

6.聚合日志

7.列表流

8.获取系统信息

技能和代理（v2.3.0+）

技能

代理

查询示例

搜索错误

搜索特定端点

搜索HTTP状态代码

搜索用户操作

搜索慢速请求

搜索例外情况

结合多种条件

使用通配符搜索

按字段存在搜索

常见用例

1.调试生产错误

2.监控最近的部署

3.调查API故障

错误消息

故障排除

服务器无法启动

身份验证错误

未返回任何结果

集成测试失败

发展

先决条件

开发工作流程

项目结构

运行测试

建筑

贡献

更新日志

安全

许可证

链接

致谢

相关 MCP

Excel文件处理服务

前端开发AI集成服务器

Tempo MCP服务器

可观测性堆栈

可观测性数据访问MCP服务

OpenTelemetry智能分析服务