使用说明

Signoz MCP服务器

一个MCP（模型上下文协议）服务器，向Claude公开Signoz可观察性数据，支持对日志、指标和跟踪进行自然语言查询。

特性

查询日志：使用简单的筛选器语法搜索和分析应用程序日志
查询指标：基于生成器的指标查询，具有聚合和分组功能
发现数据：探索可用指标和日志属性
统一接口：日志和指标的语法一致
类型安全：强大的时间戳处理和参数验证
生产就绪：全面的测试覆盖率和错误处理

✅ 实现

✅ 日志：使用分页和属性过滤进行查询
✅ 指标：具有多个指标、聚合和分组的生成器查询
✅ 发现：度量和日志属性发现工具
✅ 测试：45多项测试，涵盖所有功能

🚧 在开发中

🚧 痕迹：占位符-不起作用

先决条件

Signoz 0.85或更高版本（用于API v4支持）
Signoz API密钥
什么之中的一个：
- Bun运行时（用于开发）
- 预构建二进制文件发布

安装

选项1：使用预构建的二进制文件（推荐）

从以下网址下载适用于您平台的二进制文件发布页面：

signoz-mcp-darwin-arm64 -macOS苹果硅
signoz-mcp-darwin-x64 -macOS英特尔
signoz-mcp-linux-x64 -Linux x64
signoz-mcp-linux-arm64 -Linux arm64
signoz-mcp-windows-x64.exe -Windows x64

使其可执行（macOS/Linux）：

chmod +x signoz-mcp-*

[！重要] macOS用户：下载的二进制文件由Gatekeeper隔离。您有三个选择：

删除隔离： xattr -d com.apple.quarantine ./signoz-mcp-darwin-*

使用Bun从源代码运行（见下面的选项2）

在本地构建二进制文件： bun run build

选项2：从源代码构建

# Clone the repository
git clone <repository-url>
cd signoz-mcp-server

# Install dependencies
bun install

配置

Claude代码集成

有多种方法可以使用Claude代码配置Signoz MCP服务器：

方法1：项目配置文件（推荐）

创建一个 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "signoz": {
      "type": "stdio",
      "command": "/path/to/signoz-mcp-server-binary",
      "env": {
        "SIGNOZ_API_KEY": "your-api-key-here",
        "SIGNOZ_API_URL": "https://your-signoz-instance.com"
      }
    }
  }
}

或者，如果从源代码运行：

{
  "mcpServers": {
    "signoz": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/signoz-mcp-server/src/server.ts"],
      "env": {
        "SIGNOZ_API_KEY": "your-api-key-here",
        "SIGNOZ_API_URL": "https://your-signoz-instance.com"
      }
    }
  }
}

创建文件后：

退出克劳德代码： /exit
在同一目录中重新启动： claude -c
验证服务器是否已加载： /mcp

[！提示] 使用 claude -c 将继续您之前的Claude Code会话，这样您就不会失去任何进度，并且可以继续您中断的现有对话。

方法2:Claude CLI管理

# Add server with binary (local to current project)
claude mcp add signoz -s project -e SIGNOZ_API_KEY=your-key -e SIGNOZ_API_URL=https://your-instance.com -- /path/to/signoz-mcp-server-binary

# Add server from source
claude mcp add signoz -s project -e SIGNOZ_API_KEY=your-key -e SIGNOZ_API_URL=https://your-instance.com -- bun run /path/to/signoz-mcp-server/src/server.ts

# List configured servers
claude mcp list

# View server configuration
claude mcp get signoz

# Remove server
claude mcp remove signoz

范围选项：

--scope local （默认）：仅在当前项目中可用
--scope project：通过共享 .mcp.json 文件
--scope user：适用于所有项目

[！注意] 本地作用域配置存储在 ~/.claude.json 下：
{
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        // your server config here
      }
    }
  }
}

方法3：克劳德桌面应用程序

看 docs/configuration.md 有关Claude Desktop配置的详细信息，请参阅上述方法1中的示例JSON片段。

用法

发展

bun run dev

MCP检验员测试

bun run inspector

这将启动MCP检查器http://localhost:6274在那里，您可以交互式地测试服务器的工具。

构建

bun run build

快速测试

bun run test

可用工具

query_logs

使用简化的过滤器语法从Signoz查询应用程序日志，输出清晰可读。

主要特点：

默认最小输出：清洁 [timestamp] [level] [service-context] message 格式
智能服务上下文：显示 [service-name] 或 [namespace/deployment] 自动地
详细模式：需要时提供完整的属性详细信息(verbose: true)
属性过滤：仅包括特定属性(include_attributes: [...])
自动分页：处理大型结果集，并为下一页提供明确说明

该工具接受具有以下运算符的简单过滤器语法：

key=value -完全匹配
key~value -包含（用于在日志正文中搜索）
key!=value -不等于

使用AND连接多个过滤器：

k8s.deployment.name=stio-api -按Kubernetes部署筛选
level=error AND service=api-gateway -多个过滤器
body~timeout -消息中包含“超时”的日志
k8s.namespace=production AND body~error -结合资源和内容过滤器

输出示例：

默认压缩模式：

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.

[2025-06-17T22:26:41Z] [ERROR] [api-gateway]
Database connection timeout after 30s

[2025-06-17T22:26:40Z] [WARN] [production/user-service]
Rate limit approaching: 450/500 requests

详细模式（详细：true）：

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.
Attributes: http.request.id=abc-123 labels.module=rule trace.id=xyz-789

[2025-06-17T22:26:41Z] [ERROR] [api-gateway]
Database connection timeout after 30s
Attributes: error.type=timeout database.name=users http.status=500

自定义属性（包括属性：[“http.request.id”，“trace.id”]）：

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.
Attributes: http.request.id=abc-123 trace.id=xyz-789

查询示例：

"Show logs from the stio-api deployment"
→ query: "k8s.deployment.name=stio-api"

"Find error logs from the api-gateway service in the last hour"
→ query: "level=error AND service=api-gateway", start: "now-1h"

"Get logs containing 'timeout' from production namespace"
→ query: "k8s.namespace=production AND body~timeout"

"Find logs with database errors, showing trace IDs"
→ query: "body~database AND body~error", include_attributes: ["trace.id"]

"Debug logs with full details"
→ query: "level=debug AND service=user-api", verbose: true

分页示例： 当结果超过限制时，该工具会提供明确的说明：

--- More Results Available ---
Oldest timestamp: 2025-06-17T23:09:19.025991988Z
To get next 100 older results, use: end="2025-06-17T23:09:19.025991988Z"

query_metrics

使用具有聚合和分组功能的基于构建器的界面查询指标。

主要特点：

多种指标：在一个请求中查询多个指标
聚合选项：平均值、最小值、最大值、总和、计数
分组：按属性对结果进行分组
筛选器语法：与日志相同（键=值，键~包含，键！=值）

示例：

"Show CPU utilization for the stio-api deployment"
→ metric: ["k8s_pod_cpu_utilization"], query: "k8s_deployment_name=stio-api"

"Compare CPU and memory usage grouped by pod"
→ metric: ["k8s_pod_cpu_utilization", "k8s_pod_memory_usage"], 
  group_by: ["k8s_pod_name"], aggregation: "avg"

"Get maximum request rates by status code"
→ metric: ["http_requests_total"], group_by: ["status_code"], 
  aggregation: "max", query: "service=api-gateway"

查询跟踪

查询分布式跟踪。

例子：

"Find traces where the total duration exceeded 1 second"

文档

使用示例 -日志查询和输出格式的综合示例
开发指南 -构建、测试和发布流程
配置指南 -设置和故障排除
API集成指南 -Signoz API详细信息和示例
规划文件 -功能路线图和设计决策

发展

建筑

# Build for current platform
bun run build

# Build for all platforms
bun run build:binary:all

# Run tests
bun test

发布

此项目使用自动语义版本控制。看开发指南有关以下内容的详细信息：

提交消息约定
自动发布流程
手动发布程序

贡献

分叉存储库
创建要素分支(git checkout -b feat/amazing-feature)
使用常规提交提交更改(git commit -m 'feat: add amazing feature')
推到分支(git push origin feat/amazing-feature)
打开Pull请求 main

许可证

麻省理工学院