签纳兹-MCP服务器
项目介绍
SigNoz MCP Server
一个提供无缝访问 SigNoz 可观察性数据的 Model Context Protocol (MCP) 服务器，通过 AI 助手和大语言模型实现。此服务器支持对指标、跟踪、日志、警报、仪表板和服务性能数据进行自然语言查询。
🚀 功能
- 列出指标键：从 SigNoz 获取所有可用的指标键。
- 按文本搜索指标：查找包含给定文本的具体指标。
- 列出警报：获取所有活动警报及其详细状态。
- 获取警报详情：检索特定警报规则的全面信息。
- 获取警报历史：提供警报的时间线。
- 日志：获取与服务、警报等相关的日志。
- 跟踪：搜索、分析、获取跟踪的层次关系和关联。
- 列出仪表板：获取仪表板概要（名称、UUID、描述、标签）。
- 获取仪表板：检索完整的仪表板配置，包括面板和查询。
- 列出服务：发现指定时间范围内的所有服务。
- 服务顶级操作：分析特定服务的性能指标。
- 查询生成器：生成复杂的响应查询。
🏗️ 架构
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP 客户端 │───▶│ MCP 服务器 │───▶│ SigNoz API │
│ (AI 助手) │ │ (Go) │ │ (可观察性) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ 工具处理器 │
│ (HTTP 客户端) │
└──────────────────┘
核心组件
- MCP 服务器：处理 MCP 协议通信
- 工具处理器：注册和管理可用工具
- SigNoz 客户端：用于 SigNoz API 交互的 HTTP 客户端
- 配置：基于环境的配置管理
- 日志记录：使用 Zap 的结构化日志记录
🧰 使用方法
使用兼容 MCP 的客户端如 Claude Desktop 和 Cursor 来使用此 mcp-server。
Claude Desktop
- 构建或定位到
signoz-mcp-server的二进制路径（例如：.../signoz-mcp-server/bin/signoz-mcp-server）。 - 前往 Claude -> 设置 -> 开发者 -> 本地 MCP 服务器点击
编辑配置。 - 编辑
claude_desktop_config.json添加如下配置，包含你的 SigNoz URL、API 密钥和指向 signoz-mcp-server 二进制的路径。
{
"mcpServers": {
"signoz": {
"command": "/绝对路径/to/signoz-mcp-server/bin/signoz-mcp-server",
"args": [],
"env": {
"SIGNOZ_URL": "https://你的-signoz实例.com",
"SIGNOZ_API_KEY": "你的-api-key-here",
"LOG_LEVEL": "info"
}
}
}
}
- 重启 Claude Desktop。你应该能在开发者控制台中看到加载的
signoz服务器，并且其工具变得可用。
注意事项：
- 替换
command路径为你实际的二进制位置。
Cursor
选项 A — 图形界面：
- 打开 Cursor → 设置 → Cursor 设置 → 工具与集成 →
+新 MCP 服务器
选项 B — 项目配置文件：
在项目根目录创建 .cursor/mcp.json：
对于两种选项都使用相同的 JSON 结构
{
"mcpServers": {
"signoz": {
"command": "/绝对路径/to/signoz-mcp-server/bin/signoz-mcp-server",
"args": [],
"env": {
"SIGNOZ_URL": "https://你的-signoz实例.com",
"SIGNOZ_API_KEY": "你的-api-key-here",
"LOG_LEVEL": "info"
}
}
}
}
添加后，重启 Cursor 以使用 SigNoz 工具。
基于 HTTP 的自托管 mcp 服务器
Claude Desktop
- 使用环境变量构建并运行 signoz-mcp-server
- SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
- 或使用 docker-compose
- 前往 Claude -> 设置 -> 开发者 -> 本地 MCP 服务器点击
编辑配置。 - 编辑
claude_desktop_config.json添加如下配置，包含你的 SigNoz URL、API 密钥和指向 signoz-mcp-server 二进制的路径。
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer 你的-api-key-here"
}
}
}
}
注意：你可以通过以下方式传递 SigNoz API 密钥：
- 在启动服务器时作为环境变量（
SIGNOZ_API_KEY），或者 - 如上所示，在客户端配置中的
Authorization头中传递
- 重启 Claude Desktop。你应该能在开发者控制台中看到加载的
signoz服务器，并且其工具变得可用。
Cursor
构建并运行 signoz-mcp-server 使用环境变量 - SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server - 或使用 docker-compose
选项 A — 图形界面：
- 打开 Cursor → 设置 → Cursor 设置 → 工具与集成 →
+新 MCP 服务器
选项 B — 项目配置文件：
在项目根目录创建 .cursor/mcp.json：
对于两种选项都使用相同的 JSON 结构
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer signoz-api-key-here"
}
}
}
}
注意：你可以通过以下方式传递 SigNoz API 密钥：
- 在启动服务器时作为环境变量（
SIGNOZ_API_KEY），或者 - 如上所示，在客户端配置中的
Authorization头中传递
注意：默认情况下，服务器的日志级别设置为 info。如果你需要详细的调试信息，请在环境中设置 LOG_LEVEL=debug。对于生产用途，考虑使用 LOG_LEVEL=warn 以减少日志冗余。
🛠️ 开发指南
先决条件
- Go 1.25 或更高版本
- 具有 API 访问权限的 SigNoz 实例
- 有效的 SigNoz API 密钥
项目结构
signoz-mcp-server/
├── cmd/server/ # 主应用程序入口点
├── internal/
│ ├── client/ # SigNoz API 客户端
│ ├── config/ # 配置管理
│ ├── handler/tools/ # MCP 工具实现
│ ├── logger/ # 日志记录工具
│ └── mcp-server/ # MCP 服务器核心
├── go.mod # Go 模块依赖
├── Makefile # 构建自动化
└── README.md
从源码构建
# 克隆仓库
git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
# 构建二进制文件
make build
# 或直接使用 Go 构建
go build -o bin/signoz-mcp-server ./cmd/server/
配置
设置以下环境变量：
export SIGNOZ_URL="https://你的-signoz实例.com"
export SIGNOZ_API_KEY="你的-api-key-here"
export LOG_LEVEL="info" # 可选：debug, info, error (默认：info)
在 SigNoz Cloud 中，SIGNOZ_URL 通常是 - https://ingest.<区域>.signoz.cloud
你可以在 SigNoz UI 中通过前往 设置 -> 工作区设置 -> API 密钥 获取 API 密钥
运行服务器
# 运行构建的二进制文件
./bin/signoz-mcp-server
开发工作流程
- 添加新工具：在
internal/handler/tools/中实现 - 扩展客户端：在
internal/client/client.go中添加方法 - 注册工具：添加到适当的处理器注册
- 测试：使用 MCP 客户端验证功能
📖 用户指南
对于 AI 助手及大语言模型
MCP 服务器提供了可以通过自然语言使用的以下工具：
指标探索
"显示所有可用指标"
"搜索与 CPU 相关的指标"
警报监控
"列出所有活动警报"
"获取警报规则 ID abc123 的详细信息"
"显示警报规则 abc123 在过去 6 小时的历史"
"获取与警报 abc456 相关的日志"
仪表板管理
"列出所有仪表板"
"显示主机指标仪表板的详细信息"
服务分析
"列出过去 6 小时的所有服务"
"支付服务的顶级操作是什么？"
日志分析
"列出所有保存的日志视图"
"显示支付服务在过去一小时的错误日志"
"搜索支付服务日志中的 '连接超时' 错误"
"获取严重程度为 FATAL 的错误日志"
跟踪分析
"显示所有可用的跟踪字段"
"搜索苹果服务在过去一小时的跟踪"
"获取跟踪 ID ball123 的详细信息"
"检查随机服务跟踪中的错误模式"
"显示跟踪 xyz789 的跨度层级"
"查找过去 2 小时内带有错误的跟踪"
"给我这个跟踪的流程"
工具参考
signoz_list_metric_keys
列出 SigNoz 中所有可用的指标键。
signoz_search_metric_by_text
通过文本搜索指标（使用 SigNoz 聚合属性自动完成）。
- 参数：
searchText（必需）- 要搜索的文本
signoz_list_alerts
列出 SigNoz 中所有活动的警报。
signoz_get_alert
获取特定警报规则的详细信息。
- 参数：
ruleId（必需）- 警报规则 ID
signoz_list_dashboards
列出所有仪表板的概要（名称、UUID、描述、标签）。
- 返回：简化后的仪表板信息，便于 LLM 处理
signoz_get_dashboard
获取完整的仪表板配置。
- 参数：
uuid（必需）- 仪表板 UUID
signoz_list_services
列出指定时间范围内的所有服务。
- 参数：
timeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以纳秒为单位的开始时间（默认为 6 小时前）end（可选）- 以纳秒为单位的结束时间（默认为现在）
signoz_get_service_top_operations
获取特定服务的顶级操作。
- 参数：
service（必需）- 服务名称timeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以纳秒为单位的开始时间（默认为 6 小时前）end（可选）- 以纳秒为单位的结束时间（默认为现在）tags（可选）- 标签的 JSON 数组
signoz_get_alert_history
获取特定规则的警报历史时间线。
- 参数：
ruleId（必需）- 警报规则 IDtimeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以毫秒为单位的开始时间戳（默认为 6 小时前）end（可选）- 以毫秒为单位的结束时间戳（默认为现在）offset（可选）- 分页偏移量（默认：0）limit（可选）- 结果数量限制（默认：20）order（可选）- 排序顺序：'asc' 或 'desc'（默认：'asc'）
signoz_list_log_views
列出 SigNoz 中所有已保存的日志视图。
- 返回：包含名称、ID、描述和查询细节的概要
signoz_get_log_view
根据 ID 获取特定日志视图的完整详细信息。
- 参数：
viewId（必需）- 日志视图 ID
signoz_get_logs_for_alert
自动获取与特定警报相关的日志。
- 参数：
alertId（必需）- 警报规则 IDtimeRange（可选）- 警报周围的时长（例如，'1h'、'30m'、'2h'）- 默认：'1h'limit（可选）- 返回的最大日志数（默认：100）
signoz_get_error_logs
获取具有 ERROR 或 FATAL 严重性的日志。
- 参数：
timeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以毫秒为单位的开始时间（默认为 6 小时前）end（可选）- 以毫秒为单位的结束时间（默认为现在）service（可选）- 用于过滤的服务名称limit（可选）- 返回的最大日志数（默认：100）
signoz_search_logs_by_service
在特定服务的时间范围内搜索日志。
- 参数：
service（必需）- 要搜索日志的服务名称timeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以毫秒为单位的开始时间（默认为 6 小时前）end（可选）- 以毫秒为单位的结束时间（默认为现在）severity（可选）- 日志严重性过滤器（DEBUG、INFO、WARN、ERROR、FATAL）searchText（可选）- 要在日志主体中搜索的文本limit（可选）- 返回的最大日志数（默认：100）
signoz_get_trace_field_values
获取跟踪的可用字段值。
- 参数：
fieldName（必需）- 要获取值的字段名称（例如，'service.name'、'http.method'）searchText（可选）- 用于过滤值的搜索文本
signoz_search_traces_by_service
搜索特定服务的跟踪。
- 参数：
service（必需）- 要搜索跟踪的服务名称timeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以毫秒为单位的开始时间（默认为 6 小时前）end（可选）- 以毫秒为单位的结束时间（默认为现在）operation（可选）- 用于过滤的操作名称error（可选）- 按错误状态过滤（true/false）minDuration（可选）- 最小持续时间（纳秒）maxDuration（可选）- 最大持续时间（纳秒）limit（可选）- 返回的最大跟踪数（默认：100）
signoz_get_trace_details
获取跟踪信息，包括所有跨度和元数据。
- 参数：
traceId（必需）- 要获取详细信息的跟踪 IDtimeRange（可选）- 时间范围，如 '2h'、'6h'、'2d'、'7d'start（可选）- 以毫秒为单位的开始时间（默认为 6 小时前）end（可选）- 以毫秒为单位的结束时间（默认为现在）includeSpans（可选）- 包含详细跨度信息（true/false，默认：true）
signoz_get_trace_error_analysis
分析跟踪中的错误模式。
- 参数：
timeRange