内容
# SigNoz MCP 服务器
[](https://golang.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
一个 Model Context Protocol (MCP) 服务器，提供通过 AI 助手和 LLMs 无缝访问 SigNoz 可观察性数据。 使用自然语言查询指标、跟踪、日志、警报、仪表板和服务。
**[📖 完整文档](https://signoz.io/docs/ai/signoz-mcp-server/)**
## 目录
- [连接到 SigNoz Cloud](#connect-to-signoz-cloud)
- [自托管安装](#self-hosted-installation)
- [连接到自托管 SigNoz](#connect-to-self-hosted-signoz)
- [您可以做什么](#what-can-you-do-with-it)
- [可用工具](#available-tools)
- [环境变量](#environment-variables)
- [Claude 桌面扩展](#claude-desktop-extension)
- [架构](#architecture)
- [贡献](#contributing)
## 连接到 SigNoz Cloud
将您的 AI 工具连接到 SigNoz Cloud 的托管 MCP 服务器。 无需安装；只需添加托管的 MCP URL 并进行身份验证。
```text
https://mcp.<region>.signoz.cloud/mcp
```
> 确保您选择与 SigNoz Cloud 账户匹配的正确区域。 使用错误的区域将导致身份验证失败。
>
> 在 SigNoz 中，在 **设置 → 数据采集** 下找到您的区域，或参见 [SigNoz Cloud 区域参考](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint).
### 一键安装链接
GitHub 不可靠地处理自定义协议链接，如 `cursor://` 和 `vscode:`。
使用文档页面的一键安装按钮：
- [打开 Cursor 的一键安装链接](https://signoz.io/docs/ai/signoz-mcp-server/#install-in-one-click)
- [打开 VS Code 的一键安装链接](https://signoz.io/docs/ai/signoz-mcp-server/#install-in-one-click-1)
如果您愿意，可以使用下面的手动配置示例。
### Cursor
#### 手动配置
将此配置添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"signoz": {
"url": "https://mcp.<region>.signoz.cloud/mcp"
}
}
}
```
需要帮助？请参阅 [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)。
### VS Code / GitHub Copilot
#### 手动配置
将此配置添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"signoz": {
"type": "http",
"url": "https://mcp.<region>.signoz.cloud/mcp"
}
}
}
```
需要帮助？请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。
### Claude 桌面
将 SigNoz Cloud 添加为 Claude 桌面中的自定义连接器：
1. 打开 Claude 桌面。
2. 进入 **设置 → 开发者**（或 **功能**，取决于您的版本）。
3. 点击 **添加自定义连接器** 或 **添加远程 MCP 服务器**。
4. 输入您的 SigNoz MCP URL：`https://mcp.<region>.signoz.cloud/mcp`
当提示时，完成身份验证流程。
### Claude 代码
运行此命令以添加托管的 SigNoz MCP 服务器：
```bash
claude mcp add --scope user --transport http signoz https://mcp.<region>.signoz.cloud/mcp
```
在终端中配置 MCP 服务器后，进行身份验证：
```bash
claude /mcp
```
选择 `signoz` 服务器并完成身份验证流程。
### OpenAI Codex
运行此命令以添加托管的 SigNoz MCP 服务器：
```bash
codex mcp add signoz --url https://mcp.<region>.signoz.cloud/mcp
```
或将此配置添加到 `config.toml`：
```toml
[mcp_servers.signoz]
url = "https://mcp.<region>.signoz.cloud/mcp"
```
添加服务器后，进行身份验证：
```bash
codex mcp login signoz
```
然后在 Codex 中运行 `/mcp` 以验证连接。
### SigNoz Cloud 身份验证
当您将托管的 MCP URL 添加到客户端时，客户端会启动身份验证流程。 您将被提示输入：
1. 您的 SigNoz 实例 URL（例如，`your-instance.signoz.cloud`）。 接受无协议的 URL；路径、查询参数和片段将被忽略。
2. 您的 API 密钥
在 SigNoz 中，在 **设置 → API 密钥** 下创建 API 密钥。 只有 **管理员** 用户可以创建 API 密钥。
## 自托管安装
### 下载二进制文件（推荐）
从 [GitHub Releases](https://github.com/SigNoz/signoz-mcp-server/releases) 下载最新的二进制文件：
```bash
# macOS (Apple Silicon)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_arm64.tar.gz | tar xz
# macOS (Intel)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_amd64.tar.gz | tar xz
# Linux (amd64)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_amd64.tar.gz | tar xz
```
这会在当前目录中解压出一个 `signoz-mcp-server` 二进制文件。 将其移动到您的 PATH 中的某个位置，或记录下用于以下配置的绝对路径。
### Go 安装
```bash
go install github.com/SigNoz/signoz-mcp-server/cmd/server@latest
```
二进制文件安装为 `server`，位于 `$GOPATH/bin/`（默认为 `$HOME/go/bin/server`）。 您可能需要重命名它：
```bash
mv "$(go env GOPATH)/bin/server" "$(go env GOPATH)/bin/signoz-mcp-server"
```
### Docker
Docker 镜像可在 [Docker Hub](https://hub.docker.com/r/signoz/signoz-mcp-server/tags) 上找到：
```bash
docker pull signoz/signoz-mcp-server:latest
```
在 HTTP 模式下运行：
```bash
docker run -p 8000:8000 \
-e TRANSPORT_MODE=http \
-e MCP_SERVER_PORT=8000 \
-e SIGNOZ_URL=https://your-signoz-instance.com \
-e SIGNOZ_API_KEY=your-api-key \
signoz/signoz-mcp-server:latest
```
使用特定的版本标签（例如 `v0.1.0`）而不是 `latest` 进行固定部署。
### 从源代码构建
```bash
git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
make build
```
二进制文件位于 `./bin/signoz-mcp-server`。
## 连接到自托管 SigNoz
### 先决条件
- 运行中的 [SigNoz](https://signoz.io) 实例
- SigNoz v0.120.0 或更高版本，用于使用 `/api/v2/rules` API 的警报规则工具
- SigNoz API 密钥（SigNoz UI 中的设置 → API 密钥）
- `signoz-mcp-server` 二进制文件（参见 [自托管安装](#self-hosted-installation)）
### Stdio 模式（Claude 桌面 / Cursor / 任意 MCP 客户端）
将以下内容添加到您的 MCP 客户端配置（`claude_desktop_config.json`、`.cursor/mcp.json`等）中。 将 `command` 路径替换为您的 `signoz-mcp-server` 二进制文件的绝对路径：
```json
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server",
"args": [],
"env": {
"SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_API_KEY": "your-api-key-here",
"LOG_LEVEL": "info"
}
}
}
}
```
### HTTP 模式
#### 使用 OAuth（多租户 / 云）
启动服务器：
```bash
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
OAUTH_ENABLED=true \
OAUTH_TOKEN_SECRET=$(openssl rand -base64 32) \
OAUTH_ISSUER_URL=https://your-public-mcp-url.com \
./signoz-mcp-server
```
客户端配置 - 只需 URL，无需密钥：
```json
{
"mcpServers": {
"signoz": {
"url": "https://your-public-mcp-url.com/mcp"
}
}
}
```
客户端自动发现 OAuth 端点，打开浏览器获取凭证，并处理令牌交换。
#### 无 OAuth（简单设置）
API 密钥和 SigNoz URL 只需要在 **一个** 地方提供 - 在服务器或客户端上。
**选项 A - 服务器上的凭证**（更简单的客户端配置）：
```bash
SIGNOZ_URL=https://your-signoz-instance.com \
SIGNOZ_API_KEY=your-api-key \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
./signoz-mcp-server
```
```json
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp"
}
}
}
```
**选项 B - 客户端上的 API 密钥**（服务器持有 URL，客户端发送密钥）：
```bash
SIGNOZ_URL=https://your-signoz-instance.com \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
./signoz-mcp-server
```
```json
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp",
"headers": {
"SIGNOZ-API-KEY": "your-api-key-here"
}
}
}
}
```
### HTTP 探针端点
HTTP 模式公开未经身份验证的探针端点。 新的 Kubernetes 部署应使用 `/livez` 进行 `livenessProbe`，使用 `/readyz` 进行 `readinessProbe`。
| 端点 | 目的 |
|----------|---------|
| `/livez` | 浅层存活探测。 返回 `200 OK`，当服务器进程可以回答 HTTP 请求时。 它不检查依赖项。 |
| `/readyz` | 就绪探测。 仅当 Pod 准备好接收流量时返回 `200 OK`；目前这需要 docs 索引准备就绪。 否则返回 `503`。 |
| `/healthz` | 遗留/通用健康检查，为保持向后兼容性而保留。 它遵循与 `/readyz` 相同的严格状态；使用 `/livez` 进行浅层存活。 |
## 您可以用它做什么
```
"显示所有可用的指标"
"HTTP 请求持续时间的 P99 延迟是多少？"
"列出所有活跃的警报"
"显示过去一小时的 paymentservice 错误日志"
"过去一小时内每个服务的错误数量是多少？"
"搜索过去一小时内的 checkout 服务跟踪"
"获取跟踪 ID abc123 的详细信息"
"创建包含 CPU 和内存小部件的仪表板"
"如何将 Docker 日志发送到 SigNoz？"
```
## 可用工具
> **SigNoz 兼容性：** 警报规则工具针对 `/api/v2/rules/*`，可在 SigNoz v0.120.0 及更高版本中使用。 自托管部署在较旧的 SigNoz 版本上将看到 HTTP 404 错误。 通知通道工具针对 render-envelope `/api/v1/channels/*` 路由，由 SigNoz/signoz#10941、#10957、#10995 和 #10997 引入。
> **工具元数据：** 每个工具都接受 `searchContext`，即用户的原始问题/搜索文本。 用于 MCP 可观察性，不转发到 SigNoz API。
| 工具 | 描述 |
|------|-------------|
| `bylonis_list_metrics` | 搜索和列出可用的指标 |
| `bylonis_query_metrics` | 查询指标并具有智能聚合默认值 |
| `bylonis_get_field_keys` | 发现指标、跟踪或日志的可用字段键 |
| `bylonis_get_field_values` | 获取字段键的可能值 |
| `bylonis_list_alerts` | 列出当前正在触发/静默/抑制的 Alertmanager 警报实例（不是规则定义） |
| `bylonis_list_alert_rules` | 列出已配置的警报规则，包括非活动/OK 和禁用规则 |
| `bylonis_get_alert` | 通过 GET /api/v2/rules/{ruleId} 获取警报规则定义 |
| `bylonis_get_alert_history` | 获取警报状态历史时间线 |
| `bylonis_create_alert` | 通过 POST /api/v2/rules/ 创建警报规则；v2alpha1 用于阈值/promql，v1 用于异常 |
| `bylonis_update_alert` | 通过 PUT /api/v2/rules/{ruleId} 更新警报规则 |
| `bylonis_delete_alert` | 通过 DELETE /api/v2/rules/{ruleId} 删除警报规则 |
| `bylonis_list_dashboards` | 列出所有仪表板及其摘要 |
| `bylonis_get_dashboard` | 获取完整的仪表板配置 |
| `bylonis_create_dashboard` | 创建新的仪表板 |
| `bylonis_update_dashboard` | 更新现有的仪表板 |
| `bylonis_delete_dashboard` | 删除仪表板 |
| `bylonis_import_dashboard` | 从路径创建仪表板 SigNoz/dashboards 模板 |
| `bylonis_list_dashboard_templates` | 列出捆绑的 SigNoz 仪表板模板目录，以便模型可以选择模板 |
| `bylonis_list_services` | 列出指定时间范围内的服务 |
| `bylonis_get_service_top_operations` | 获取服务的顶级操作 |
| `bylonis_list_views` | 列出指定 sourcePage（跟踪/日志/指标）的已保存的 Explorer 视图 |
| `bylonis_get_view` | 通过 UUID 获取已保存的视图 |
| `bylonis_search_docs` | 搜索官方 SigNoz 文档的产品、设置、配置、API、部署或故障排除问题 |
| `bylonis_fetch_doc` | 获取官方 SigNoz 文档页面的完整 Markdown 或标题 |
| `bylonis_create_view` | 创建新的已保存的 Explorer 视图 |
| `bylonis_update_view` | 替换现有的已保存视图（完整主体 PUT） |
| `bylonis_delete_view` | 删除 UUID 的已保存视图 |
| `bylonis_aggregate_logs` | 聚合日志（计数、平均值、p99 等）并分组 |
| `bylonis_search_logs` | 搜索日志并具有灵活的过滤 |
| `bylonis_aggregate_traces` | 聚合跟踪统计并分组 |
| `bylonis_search_traces` | 搜索跟踪并具有灵活的过滤 |
| `bylonis_get_trace_details` | 获取完整的跟踪及其所有跨度 |
| `bylonis_execute_builder_query` | 执行原始 Query Builder v5 查询 |
| `bylonis_list_notification_channels` | 列出通知通道 |
| `bylonis_get_notification_channel` | 获取单个通知通道 ID |
| `bylonis_create_notification_channel` | 创建通知通道并发送测试通知 |
| `bylonis_update_notification_channel` | 更新通知通道并发送测试通知 |
| `bylonis_delete_notification_channel` | 删除通知通道 ID |
有关详细用法和示例，请参阅 [full 文档](https://signoz.io/docs/ai/signoz-mcp-server/)。
`bylonis_import_dashboard`
从托管在Noz/dashboards](https://github.com/Sz/dashboards) `main` 分支）中的精选模板创建仪表盘。服务器获取模板 JSON它，并在一次调用中创建仪表盘。
要发现可，请先调用 `by_list_dashboard_templates`选择最佳匹配 **参数：**
path`（必填）– SigNoz/dashboards 仓库内的模板路径，例如 `hostmetrics/hostmetrics.json`
#### `bylonis_list_dashboard_templates`
返回 SigNoz 精选仪表盘模板的完整捆绑目录（id、title、path、description、category、keywords）作为 JSON 数组。与 `bylonis_import_dashboard` 配对使用：让模型读取目录，选择与用户意图的条目，然后path` - **参数：**#### `bylonis_update更新现有的。
- **参数： - `uuid`）– 要更新的的唯一标识符
- `dashboard`（– 表示更新后状态仪表盘对象
title`（必填）仪表盘名称 - `description`（可选 仪表盘显示内容的简要摘要
- `tags`（可选）– 应用于仪表盘的标签 - `layout必填）– 网格
- `（可选）中可用的变量映射 - `widgets`（必填）– 定义更新后的完整部件集
#### `bylonis_list列出某个时间范围内的所有服务。
- **参数：**
- `time（可选）- 时间范围，如 '2h',h', '2d7d'（ `start` 和 `end` 时忽略）
- `start`（可选）- 开始时间（纳秒）（默认为 6 小时前 - `end`（可选）- 结束纳秒）（默认为当前
#### `by_get_service_top_operations`
服务的顶级操作。
- **参数：**
service`（必填）- 服务名称
-Range`（可选）- 时间范围，如 '2h', '6h', '2d', '7d'（当提供 `start `end` 时 - `start`（可选）- 开始时间秒）（默认为 6 小时前）
-`（可选）- 结束时间（纳秒）（默认为当前时间）
- `（可选）- JSON 类型的标签数组 `bylonis_get`
获取特定规则报历史时间线。
参数：**
ruleId`（必填）- 警报规则 ID
- `timeRange`）- 时间范围，如 '2h', '6h', '2d', '7d'（当start` 和 `end` 时忽略）
- `start`（可选）- 开始时间戳（毫秒）（默认为 6 小时前）
- `end`（可选）- 结束时间戳（毫秒）（默认为当前时间）
- `offset`（可选）- 分页偏移量（默认：0）
- `limit`（可选）- 结果数量限制（默认：20）
-`（可选）- 排序顺序：'asc 'desc'（'asc'） `bylonis_list_views`
列出给定 `` 的 SigNoz 已保存的 Explorer 视图分页；响应包含total`、`has 和 `nextOffset`块。
- ****
- `sourcePage`（必填）- 以下之一：`traces`、`logs`、`metrics`
`name`（可选 视图名称筛选器（服务器端 - `category`）- 视图匹配筛选器（服务器端）
- `limit可选）- 页面50）
`offset`（可选 要跳过的结果数量（默认：0）
####lonis_get_view`
通过 UUID 获取单个的视图。
- **参数：** `view（必填）- 已保存 UUID
#### `is_search_docs`
使用 BM25 在索引的上搜索官方 Sig 文档。
- ****
- `（必填）- 或关键词查询
`limit`（可选）- 返回的最大结果数（默认：10，最大）
- ``（可选）确的顶级文档部分筛选器，例如 `setup`、`logs-management`、`-distributed-tracingmetrics`、`alerts`、`dashboards`、`-apis`、`` 或 `collection`
- `search - 用户的原始问题 `bylon_doc`
从本地获取官方 SigNoz 文档页面的完整 Markdown。仅接受 `https://signoz.io/docs/...` URLdocs/...` 路- **参数：**
`url`（- 文档页面 URL
- `（可选）- 标题锚点 ID 或
- `` - 用户的
#### `signdocs/sitemap`
只 资源，包含由文档搜索和获取工具使用的索引文档站点地图。
#### `bylonis_create_view`
创建新的已 视图。
- **参数：** 符合 `SavedView`荷。
- **提示：** 在构造有效载荷前，请阅读 MCP 资源 `signoz://view/instructions` 和 `://view/examples#### `bylon_view`
替换现有的已保存视图主体 PUT）。
参数：**
- `viewId`（- 要替换的 UUID
- `（必填）- `SavedView``name`、``、`compositeQuery `category``、`extraData`一个）
- **提示：** 在构造有效前，请阅读 MCPsignoz://view` 和 `signview/examples`。调用lonis_get_view在 `view`其 `data`更改任意字段。部分主体将清除未指定的字段 `bylon_view`
通过 UUID 删除已保存的视图。
- **参数：** `viewId`（必填）- 已保存的视图 UUID
bylonis_aggregate聚合日志，、平均值、、最小值、最大值或百分位数，支持分组。
- **参数 - `aggregation必填）- 函数：count、、avg、sum、min、max、、p75、、p95、p99、rate
aggregateOn`（可选 要聚合的字段（除 count 和 rate）
- `groupBy`（可选）- 按逗号分隔的字段（例如，', severity_text' - `filter`）- 使用 SigNoz 搜索语法的 - `（可选）-的快捷筛选
`severity`（- 严重程度筛选、INFO、ERROR、FATAL）
- `orderBy`）- 排序方向（例如，() desc'）
`limit`（可选）- 返回的最大组默认：10，10000；较高服务器内存）
`timeRange`）- 时间范围30m'、'1h'、'6h'、'24h'（默认：'1h'；当同时提供 `start` 和 `end` 时忽略）
- `start` / `end`（可选）- 开始/结束时间（毫秒）。当同时提供时，它们会覆盖 `timeRange`
#### `bylonis_search搜索日志，支持灵活的筛选，涵盖。
- ****
- `query`（可选）-Noz 法的筛选表达式（例如，"service.name = 'vc' AND_code >= 400"）
- `service`（可选）- 按服务名称筛选
severity`（可选）- 严重程度DEBUG、INFO、ERROR、FATAL - `searchText`（可选）-中搜索的使用 CONTA匹配）
- `timeRange`（- 时间范围，如 '30m'、'1h'、'6h'、'24h'（默认：'1；当 `start` 和 `end` 时忽略）
`start`end`（可选）- 开始/结束时间（当同时提供时，它们会覆盖 ``
-`（可选）的最大日志数（默认：100，最大：10000；较高值 — 使用 `offset` 分页）
- `offset`（可选）- 分页偏移量（默认：0）
#### `bylonis_get_field_keys`
获取给定信号（指标、跟踪或日志）的可用字段键。
- **参数：**
- `signal`（必填）- 信号类型：`metrics`、`traces` 或 `logs`
- `searchText`（可选）- 按名称子字符串筛选字段键
- `metricName`（可选）- 按指标名称筛选（适用于指标信号）
- `fieldContext`（可选）- 按字段上下文筛选（例如resource`、`span`）
- `fieldDataType`（可选）- 按数据类型筛选（例如，`string`、`int64`）
- `source`（ 按来源筛选
#### `bylonis_get_field_values`
获取给定信号的特定字段键的可能值。
- **参数：**
- `signal`（必填）- 信号类型：`metrics`、`traces` 或 `logs`
- `name`（必填）- 要获取值的字段键（例如，`service.name`、`http.method`）
- `searchText`（可选）- 按子字符串筛选值
- `metricName`（可选）- 按指标名称筛选（适用于指标信号）
- `source`（可选）- 按来源筛选
#### `bylonis_search_traces`
搜索轨迹/跨度，支持灵活的筛选。
- **参数：**
- `query`（可选）- 使用 SigNoz 搜索筛选表达式（例如，"service.name = 'payment-svc' AND hasError = true"）
- `service`（可选）- 按服务名称筛选
- `operation`（可选）- 按操作/跨度名称筛选
- `error`（可选）- 按错误状态筛选（'true' 或 'false'）
- `minDuration` / `maxDuration`（可选）- 最小/最大跨度持续时间（纳秒）（例如，'500000000' 表示 500ms）
- `timeRange`（可选）- 时间范围，如 '30m'、'1h'、'6h'、'24h'：'1h'；当同时提供 `start` 和 `end` 时忽略）
- `start` / `end`（可选）- 开始/结束时间（毫秒）。当同时提供时，它们会覆盖 `timeRange`
- `limit`（可选）- 返回的最大轨迹数（默认：100，最大：10000；较高值会限制 — 使用 `offset` 分页）
- `offset`（可选）- 分页偏移量（默认：0）
#### `bylonis_aggregate_traces`
聚合轨迹统计数据，如计数、平均值、求和、最小值、最大值或百分位数，支持按字段分组。
- **参数：**
- `aggregation`（必填）- 聚合函数：count、count_distinct、avg、sum、min、max、p50、p75、p90、p95、p99、rate
- `aggregateOn`（可选）- 要聚合的字段（例如，'durationNano'）。除 count 和 rate 外必填
- `groupBy`（可选）- 按逗号分隔的字段进行例如，'service.name, name'）
- `filter`（可选）- 使用 SigNoz 搜索语法的筛选表达式
- `service`（可选）- 服务名称的快捷筛选
- `operation`（可选）- 跨度/操作名称的快捷筛选
- `error`（可选）- 错误跨度的快捷筛选（'true' 或 'false'）
- `orderBy`（可选）- 排序表达式和方向（例如，'avg(durationNano) desc'）
- `limit`（可选）- 返回的最大组数（默认：10，最大：10000；较高值会限制服务器内存）
- `timeRange`（可选）- 时间范围，如 '30m'、'1h'、'6h'、'24h'（默认：'1h'；当同时提供 `start` 和 `end` 时忽略）
- `start` / `end`（可选）- 开始/结束时间（毫秒）。当同时提供时，它们会覆盖 `timeRange`
#### `bylonis_get_trace_details`
获取轨迹信息，包括所有跨度和元数据。
- **参数：**
- `traceId`（必填）- 要获取详细信息的轨迹 ID
- `timeRange`（可选）- 时间范围，如 '2h', '6h', '2d', '7d'（当提供 `start` 和 `end` 时忽略）
- `（可选）- 开始时间（毫秒）（默认为 6 小时前）
- `end）- 结束时间（毫秒）（时间）
-ans`（- 包含度信息（true默认：true）
#### `bylonis_create_alert`
通过 `POST /api/v2/rules SigNoz新的警报- **参数：** 符合 SigNoz 警报规则架构的 JSON 有效载荷。
- **架构因 `ruleType` 而异**：
- `threshold_rule` / `promql_rule` → **v2alpha1**（结构化的 `condition.thresholds`、`evaluation`、`notificationSettings - `_rule` → **v1** 架构：顶级 `evalWindow` 和 `frequency`；``/`matchType`/`target``/`season；`compositeQuery[].spec.functions`。省略s`、`evaluationschemaVersion` **提示：**有效载荷阅读 MCP 资源 `signoz://alert/instructions `signoz://alert/examples`（这 个规范的z PR #110载荷以及累计预算示例）。对于 `promql，还请阅读oz://promstructions` — OTel 带点的指标名称3.x UTF-8 引号选择器表单。
#### `bylonis_update_alert`
通过 `PUT /api/v2/rules/{ruleId现有的警报规则。替换完整的规则 首先使用 `bylonis_get_alert` 获取当前规则，并在其基础上合并更改。
- **参数：**
- `ruleId`（必填）- 要更新的规则的 UUIDv7（从 `bylonis_list_alert_rules` / `bylonis_get_alert` 获取）。
- 另外，所有警报规则架构字段（与 `bylonis_create_alert` 形状相同）。
#### `bylonis_delete通过 `DELETE /api/v2/rulesId}` 删除规则。不可 请先与- **参数：**
- `ruleId`（必填）- 要删除的规则的 UUIDv7。服务器拒绝非 UUIDv7报错为 `invalid_input`。
#### `bylonis_delete_dashboard`
通过 UUID 删除仪表盘。
- **参数：** `uuid`（必填）- 要删除盘 UUID
#### `bylonis_list_notification_channels`
列Noz的通知通道。
- **参数：**
- `limit`（可选）- 返回数（默认）
- `offset`（可选）- 分页偏移量（默认：0）
#### `bylon_notification_channel`
创建通知通道并发送测试- **参数 - `（必填）- 通道类型：slack、webhook、pagerdemail、ie、msteams
`）- 通道名称
特定的字段（由通道类型要求），例如 `slack_api_url`、`webhook、`pagerduty_routing_key`、`email_to`、`opsgenie_api_key` 或 `msteams_webhook_url`
#### `bylonis_update_notification_channel`
更新现有的通知通道并发送测试通知。
- **参数：**
- `id`（必填）- - 通知通道 UUID
- `type`（必填）- 通道类型
- `name`（必填）- 通道名称
- 选定通道类型所需的完整通道配置字段
#### `bylonis_get_notification_channel`
通过 ID 获取单个通知通道（`GET /api/v1/channels/{id}`）。
- **参数：**
- `id`（必填）- 通知通道 UUID
#### `bylonis_delete_notification_channel`
通过 ID 删除通知通道（`DELETE /api/v1/channels/{id}`）。不可逆 — 警告如果仍有警报规则引用此通道。
- **参数：**
- `id`（必填）- 通知通道 UUID
#### `bylonis_execute_builder_query`
执行 SigNoz 查询构建器 v5 查询。
- **参数：** `query`（必填）- 完整的 SigNoz 查询构建器 v5 JSON 对象
- **查询类型：** 信封的 `compositeQuery.queries[i].type` 选择规范形状：
- `builder_query` — 信号特定的规范（日志/跟踪/指标）具有筛选器、聚合、groupBy 等。
- `builder_formula` — 公式表达式，引用其他查询名称（例如，`A / B * 100`）。
- `promql` — `{name, query, disabled, step?, legend?}`。OTel 指标的 PromQL 需要 Prometheus 3.x UTF-8 引号选择器表单 `{ "metric.name.with.dots" }`；阅读 `signoz://promql/instructions` 资源获取详细信息。
- `clickhouse_sql` — `{name, query, disabled, legend?}`。
- **文档：** 参见 [SigNoz 查询构建器 v5 文档](https://signoz.io/docs/userguide/query-builder-v5/)
## 环境变量
| 变量名 | 描述 | 是否必需 |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| `SIGNOZ_URL` | SigNoz 实例 URL | 是（stdio）；可选（http 启用 OAuth） |
| `SIGNOZ_API_KEY` | SigNoz API 密钥（在 SigNoz UI 的设置 → API 密钥中获取） | 是（stdio）；可选（http 启用 OAuth） |
| `LOG_LEVEL` | 日志级别：`info`（默认），`debug`，`warn`，`error` | 否 |
| `TRANSPORT_MODE` | MCP 传输模式：`stdio`（默认）或 `http` | 否 |
| `MCP_SERVER_PORT` | HTTP 传输模式下的端口 | 仅当 `TRANSPORT_MODE=http` 时需要 |
| `MCP_MAX_REQUEST_BYTES` | 最大传入 MCP HTTP 请求体大小（字节数，默认：`4194304` / 4 MiB） | 否 |
| `SIGNOZ_DOCS_REFRESH_INTERVAL` | 运行时文档站点地图刷新间隔（Go 时长，默认：`6h`） | 否 |
| `SIGNOZ_DOCS_FULL_REFRESH_INTERVAL` | 运行时完整文档刷新间隔（Go 时长，默认：`24h`） | 否 |
| `OAUTH_ENABLED` | 启用 OAuth 2.1 认证流程（`true`/`false`） | 否（默认：`false`） |
| `OAUTH_TOKEN_SECRET` | OAuth token 加密密钥（至少 32 字节，例如 `openssl rand -base64 32`） | 当 `OAUTH_ENABLED=true` 时需要 |
| `OAUTH_ISSUER_URL` | MCP 服务器的公共 URL（用于 OAuth 元数据发现） | 当 `OAUTH_ENABLED=true` 时需要 |
| `OAUTH_ACCESS_TOKEN_TTL_MINUTES` | 访问 token 生命周期（分钟，默认：60） | 否 |
| `OAUTH_REFRESH_TOKEN_TTL_MINUTES` | 刷新 token 生命周期（分钟，默认：1440 / 24 小时） | 否 |
| `OAUTH_AUTH_CODE_TTL_SECONDS` | 授权码生命周期（秒，默认：600 / 10 分钟） | 否 |
| `SIGNOZ_CUSTOM_HEADERS` | 附加到每个 API 请求的额外 HTTP 头部，适用于 SigNoz 在反向代理后面需要认证的场景（例如 `CF-Access-Client-Id:id.access,CF-Access-Client-Secret:secret`）格式：`Key1:Value1,Key2:Value2` | 否 |
| `SIGNOZ_INSTANCE_URL_ALLOWLIST` | 多租户（http）专用：逗号分隔的 SigNoz 后端主机允许列表，服务器将代理到这些主机。条目可以是精确主机（`signoz.example.com`）或通配符（`*.us.signoz.cloud`，匹配任何以 `.us.signoz.cloud` 结尾的子域名）；如果条目中意外包含 scheme/port/path，则会忽略这些部分并仅使用裸主机。当设置后，未在列表中的 SigNoz 实例 URL 将在每个入口处被拒绝：OAuth 设置表单和 `X-SigNoz-URL` 头部返回 HTTP 403，OAuth token 端点（包括现有的刷新 token）返回 `invalid_grant`，而 `/mcp` 请求通过 OAuth token 返回 403。所有这些情况都会增加一个 `disallowed_signoz_url` 标签的失败度量，以便告警（不会为每个请求记录日志，以避免来自配置错误/循环客户端的噪音），并且拒绝消息指向 SigNoz Cloud 用户到其区域的 MCP URL（`mcp.<region>.signoz.cloud`）并附有文档链接。空/未设置允许任何主机。操作员自己的 `SIGNOZ_URL` 被豁免。 | 否 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | MCP 服务器自己的跟踪和指标的 OTLP gRPC 端点。未配置 OTLP 端点/导出器时，内部遥测导出被禁用。对于纯文本收集器，请使用 `http://` 端点，例如 `http://localhost:4317`。 | 否 |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | 跟踪特定的 OTLP gRPC 端点；覆盖 `OTEL_EXPORTER_OTLP_ENDPOINT` 用于跟踪。 | 否 |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | 指标特定的 OTLP gRPC 端点；覆盖 `OTEL_EXPORTER_OTLP_ENDPOINT` 用于指标。 | 否 |
| `OTEL_TRACES_EXPORTER` | 设置为 `none` 以禁用内部跟踪导出，即使配置了 OTLP 端点。 | 否 |
| `OTEL_METRICS_EXPORTER` | 设置为 `none` 以禁用内部指标导出和运行时指标，即使配置了 OTLP 端点。 | 否 |
MCP 服务器不运行 OTLP 日志导出器；日志作为 JSON 输出到 stderr。因此不使用 `OTEL_LOGS_EXPORTER`。
## Claude 桌面端扩展
### 构建 Bundle
需要 **Node.js**。详见 [Anthropic MCPB](https://github.com/anthropics/mcpb)。
```bash
make bundle
```
### 安装
1. 打开 **Claude Desktop → 设置 → 开发者 → 编辑配置 → 添加 bundle.mcpb**
2. 选择 `./bundle/bundle.mcpb`
3. 输入您的 `SIGNOZ_URL`、`SIGNOZ_API_KEY`，以及可选的 `LOG_LEVEL`
4. 重启 Claude Desktop
## 架构
有关请求流程、组件交互和设计决策的详细概述，请参见 [docs/architecture.md](docs/architecture.md)。
## 贡献
有关开发工作流、所需的文档/清单同步以及 PR 检查清单，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
**为可观测性社区打造 ❤️**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器