使用说明

SigNoz MCP 服务器

一个模型上下文协议（MCP）服务器，通过人工智能助手和大型语言模型（LLMs）提供无缝访问SigNoz可观测性数据的服务。该服务器支持使用自然语言查询指标、追踪、日志、警报、仪表板以及服务性能数据。

🚀 功能

列出度量键从SigNoz中检索所有可用的指标键。
搜索度量指标键查找特定指标。
列出警报获取所有带有详细状态的活动警报。
获取警报详情获取特定警报规则的全面信息。
获取警报历史记录提供警报的时间线。
日志获取与服务、警报等相关的日志。
痕迹搜索、分析，获取轨迹的层次结构和关系。
列出仪表板获取仪表板摘要（名称、UUID、描述、标签）。
获取仪表盘检索包含面板和查询的完整仪表板配置。
列出服务在指定的时间范围内发现所有服务。
顶级运营服务分析特定服务的性能指标。
查询构建器生成查询以获取复杂响应。

🏗️ 建筑学

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  MCP Server      │───▶│   SigNoz API    │
│  (AI Assistant) │    │  (Go)            │    │  (Observability)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   Tool Handlers  │
                       │  (HTTP Client)   │
                       └──────────────────┘

核心组件

MCP 服务器处理MCP协议通信
工具处理器注册并管理可用工具
SigNoz 客户端用于SigNoz API交互的HTTP客户端
配置基于环境的配置管理
记录日志使用Zap进行结构化日志记录

🧰 使用方法

使用此MCP服务器与MCP兼容的客户端，如Claude Desktop和Cursor。

Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文决定是否需要具体翻译软件名称）

构建或定位二进制文件路径以 signoz-mcp-server （例如： .../signoz-mcp-server/bin/signoz-mcp-server）。
前往Claude -> 设置 -> 开发者 -> 点击本地MCP服务器 edit config
编辑 claude_desktop_config.json 将显示的配置添加到您的Signoz URL、API密钥以及Signoz MCP服务器二进制文件的路径中。

{
  "mcpServers": {
    "signoz": {
      "command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重启Claude桌面应用。你应该会看到 signoz 开发者控制台及其工具中的服务器负载现已可用。

注：

替换 command 将路径替换为您的实际二进制文件位置。

光标

选项A — 图形用户界面（GUI）：

打开光标 → 设置 → 光标设置 → 工具与集成 → + 新的MCP服务器

选项B — 项目配置文件：创建 .cursor/mcp.json 在你的项目根目录中：

两个选项使用相同的JSON结构

{
  "mcpServers": {
    "signoz": {
      "command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

添加后，重启 Cursor 以使用 SigNoz 工具。

基于HTTP的自托管MCP服务器

Claude Desktop（中文可译为“Claude桌面版”或“Claude桌面应用”）

构建并运行带有环境变量的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服务器” edit config
编辑 claude_desktop_config.json 将显示的配置添加到您的Signoz URL、API密钥以及指向Signoz-MCP-Server二进制文件的路径中。

{
  "mcpServers": {
    "signoz": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

注：您可以将SigNoz API密钥以以下方式传递：

一个环境变量（SIGNOZ_API_KEY在启动服务器时，或者
通过……的方式/途径 Authorization 如上所示，在客户端配置中的头部（或“标题”）

重启Claude桌面应用。你应该能看到 signoz 开发者控制台及其工具中的服务器负载现已成为可用状态。

光标

构建并运行带有环境变量的 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 — 图形用户界面（GUI）：

打开光标 → 设置 → 光标设置 → 工具与集成 → + 新的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/           # Main application entry point
├── internal/
│   ├── client/          # SigNoz API client
│   ├── config/          # Configuration management
│   ├── handler/tools/   # MCP tool implementations
│   ├── logger/          # Logging utilities
│   └── mcp-server/      # MCP server core
├── go.mod               # Go module dependencies
├── Makefile             # Build automation
└── README.md

从源代码构建

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

# Build the binary
make build

# Or build directly with Go
go build -o bin/signoz-mcp-server ./cmd/server/

配置

设置以下环境变量：


export SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_API_KEY="your-api-key-here" 
export LOG_LEVEL="info"  # Optional: debug, info, error (default: info)

在SigNoz Cloud中，SIGNOZ_URL通常是 - https://ingest。.signoz.cloud（该域名可直接翻译为“signoz的云端服务”，但通常不直接翻译，而是保留原样以表示具体的网络服务或平台名称）

您可以在SigNoz用户界面中，通过“设置”->“工作区设置”->“API密钥”来访问API密钥

运行服务器

# Run the built binary
./bin/signoz-mcp-server

开发工作流程

添加新工具实施于 internal/handler/tools/
扩展客户端添加方法到 internal/client/client.go
注册工具添加到适当的处理程序注册中
测试使用MCP客户端验证功能

📖 用户指南

对于AI助手与大型语言模型（LLMs）

MCP服务器提供了以下可通过自然语言使用的工具：

指标探索

"Show me all available metrics"
"Search for CPU-related metrics"

警报监控

"List all active alerts"
"Get details for alert rule ID abc123"
"Show me the history for alert rule abc123 from the last 24 hours"
"Get logs related to alert abc456"

仪表盘管理

"List all dashboards"
"Show me the Host Metrics dashboard details"

服务分析

"List all services from the last 24 hours"
"What are the top operations for the paymentservice?"

日志分析

"List all saved log views"
"Show me error logs for the paymentservice from the last hour"
"Search paymentservice logs for 'connection timeout' errors"
"Get error logs with FATAL severity"

痕迹分析

"Show me all available trace fields"
"Search traces for the apple service from the last hour"
"Get details for trace ID ball123"
"Check for  error patterns in traces from the randomservice"
"Show me the span hierarchy for trace xyz789"
"Find traces with errors in the last 2 hours"
"Give me flow of this trace"

工具参考

`list_metric_keys`

列出SigNoz中所有可用的指标键。

`search_metric_keys`

通过文本查询搜索指标。

参数： searchText （必填）- 要搜索的文本

`list_alerts`

列出SigNoz中的所有活动警报。

`get_alert`

获取特定警报规则的详细信息。

参数： ruleId （必填）- 告警规则ID

`list_dashboards`

列出所有仪表板及其摘要信息（名称、UUID、描述、标签）。

退货简化仪表盘信息以优化大语言模型（LLM）处理

`get_dashboard`

获取完整的仪表板配置。

参数: uuid （必填）- 仪表板 UUID

`list_services`

列出指定时间范围内的所有服务。

参数：
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间，以纳秒为单位（默认为24小时前）
- end （可选）- 结束时间（以纳秒为单位）（默认为当前时间）

`get_service_top_operations`

获取特定服务的顶级操作。

参数:
- service （必填）- 服务名称
- timeRange （可选）- 时间范围，如“2h”、“6h”、“2d”、“7d”
- start （可选）- 开始时间，以纳秒为单位（默认为24小时前）
- end （可选）- 结束时间，以纳秒为单位（默认为当前时间）
- tags （可选）- 标签的 JSON 数组

`get_alert_history`

获取特定规则的警报历史时间线。

参数：
- ruleId （必填）- 告警规则ID
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间戳（以毫秒为单位）（默认为24小时前）
- end （可选）- 结束时间戳，以毫秒为单位（默认为当前时间）
- offset （可选）- 分页偏移量（默认值：0）
- limit （可选）- 限制结果数量（默认：20）
- order （可选）- 排序顺序：'升序' 或 '降序'（默认：'升序'）

`list_log_views`

列出SigNoz中保存的所有日志视图。

退货总结包括名称、ID、描述和查询详情

`get_log_view`

通过ID获取特定日志视图的完整详细信息。

参数: viewId （必填）- 日志视图ID

`get_logs_for_alert`

自动获取与特定警报相关的日志。

参数:
- alertId （必填）- 告警规则ID
- timeRange （可选）- 警报时间范围（例如，'1h'，'30m'，'2h'）- 默认：'1h'
- limit （可选）- 要返回的日志最大数量（默认：100）

`get_error_logs`

获取指定时间范围内严重程度为ERROR或FATAL的日志。

参数：
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间（以毫秒为单位）（默认为24小时前）
- end （可选）- 结束时间（以毫秒为单位）（默认为当前时间）
- service （可选）- 用于过滤的服务名称
- limit （可选）- 要返回的日志最大数量（默认：100）

`search_logs_by_service`

在指定的时间范围内搜索特定服务的日志。

参数：
- service （必需）- 要搜索日志的服务名称
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间，以毫秒为单位（默认为24小时前）
- end （可选）- 结束时间（以毫秒为单位）（默认为当前时间）
- severity （可选）- 日志严重性过滤器（DEBUG，INFO，WARN，ERROR，FATAL）
- searchText （可选）- 在日志正文中搜索的文本
- limit （可选）- 要返回的日志最大数量（默认：100）

`get_trace_field_values`

获取追踪中可用的字段值。

参数：
- fieldName （必需）- 要获取值的字段名（例如，'service.name'，'http.method'）
- searchText （可选）- 搜索文本以过滤值

`search_traces_by_service`

搜索特定服务的痕迹。

参数:
- service （必需）- 要搜索追踪的服务名称
- timeRange （可选）- 时间范围，如“2小时”，“6小时”，“2天”，“7天”
- start （可选）- 开始时间，以毫秒为单位（默认为24小时前）
- end （可选）- 结束时间（以毫秒为单位）（默认为当前时间）
- operation （可选）- 用于过滤的操作名称
- error （可选）- 按错误状态过滤（真/假）
- minDuration （可选）- 最小持续时间（以纳秒为单位）
- maxDuration （可选）- 最大持续时间（以纳秒为单位）
- limit （可选）- 返回的最大轨迹数（默认：100）

`get_trace_details`

获取包含所有跨度（spans）和元数据的追踪信息。

参数：
- traceId （必填）- 用于获取详细信息的追踪ID
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间，以毫秒为单位（默认为24小时前）
- end （可选）- 结束时间（毫秒），默认为当前时间
- includeSpans （可选）- 包含详细的跨度信息（true/false，默认：true）

`get_trace_error_analysis`

分析轨迹中的错误模式。

参数：
- timeRange （可选）- 时间范围，如“2h”（2小时）、“6h”（6小时）、“2d”（2天）、“7d”（7天）
- start （可选）- 开始时间，以毫秒为单位（默认为24小时前）
- end （可选）- 结束时间（毫秒）（默认为当前时间）
- service （可选）- 用于过滤的服务名称
退货带有错误的追踪信息，有助于识别模式和受影响的服务

`get_trace_span_hierarchy`

获取追踪跨度关系和层次结构。

参数：
- traceId （必填）- 跟踪ID，用于获取跨度层级关系
- timeRange （可选）- 时间范围，如“2小时”、“6小时”、“2天”、“7天”
- start （可选）- 开始时间（以毫秒为单位）（默认为24小时前）
- end （可选）- 结束时间（毫秒）（默认为当前时间）

`signoz_execute_builder_query`

执行一个SigNoz查询构建器v5的查询。

参数： query （必需）- 完整的 SigNoz 查询构建器 v5 JSON 对象
文档见 SigNoz 查询构建器 v5 文档

`signoz_query_helper`

用于构建SigNoz查询的辅助工具。

参数：
- signal （可选）- 信号类型：追踪、日志或指标
- query_type （可选）- 帮助类型：字段、结构、示例，或全部
退货关于可用字段、信号类型和查询结构的指南

时间格式

大多数工具支持灵活的时间参数：

响应格式

所有工具返回的JSON响应均经过优化，以适应大型语言模型（LLM）的处理需求：

列表操作返回摘要以避免回复过多
详细操作当请求特定信息时返回完整数据
错误处理为调试提供的结构化错误信息

🔧 配置与部署

环境变量

变量	描述	必填
`SIGNOZ_URL`	SigNoz 实例 URL	是
`SIGNOZ_API_KEY` 根据上面的信息，执行如下指令：
`LOG_LEVEL`	日志级别： `info`（默认）， `debug`， `warn`， `error`	编号/序号
`TRANSPORT_MODE`	MCP传输模式： `stdio`（默认）或 `http`	编号（No）
`MCP_SERVER_PORT`	HTTP传输模式的端口	仅当`TRANSPORT_MODE=http`时为是

🤝 贡献

我们欢迎投稿！

开发环境设置

为仓库创建分支
创建一个特性分支
进行你的更改
添加测试
提交一个拉取请求

代码风格

遵循Go的最佳实践
使用有意义的变量名
为复杂逻辑添加注释
确保妥善处理错误

为可观测性社区用心打造

使用说明

SigNoz MCP 服务器

🚀 功能

🏗️ 建筑学

核心组件

🧰 使用方法

Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文决定是否需要具体翻译软件名称）

光标

基于HTTP的自托管MCP服务器

Claude Desktop（中文可译为“Claude桌面版”或“Claude桌面应用”）

光标

🛠️ 开发指南

先决条件

项目结构

从源代码构建

配置

运行服务器

开发工作流程

📖 用户指南

对于AI助手与大型语言模型（LLMs）

指标探索

警报监控

仪表盘管理

服务分析

日志分析

痕迹分析

工具参考

list_metric_keys

search_metric_keys

list_alerts

get_alert

list_dashboards

get_dashboard

list_services

get_service_top_operations

get_alert_history

list_log_views

get_log_view

get_logs_for_alert

get_error_logs

search_logs_by_service

get_trace_field_values

search_traces_by_service

get_trace_details

get_trace_error_analysis

get_trace_span_hierarchy

signoz_execute_builder_query

signoz_query_helper