金大哥 - signoz-mcp-server MCP 详情

article

README

🚀 Signoz MCP 服务器

本项目的 MCP 服务器提供了一系列工具，可用于与 Signoz 实例进行交互，如验证连接、获取仪表盘信息、获取 APM 指标等，帮助用户更方便地管理和监控 Signoz 数据。

点击下方链接观看演示视频 📽️ https://youtube.com/shorts/jxjmGyXXz7A

✨ 主要特性

MCP 服务器提供了以下工具：

test_connection：验证与 Signoz 实例的连接以及配置信息。
fetch_dashboards：列出 Signoz 中所有可用的仪表盘。
fetch_dashboard_details：通过仪表盘 ID 获取特定仪表盘的详细信息，此信息包含仪表盘的元数据，而非实时面板数据。
fetch_dashboard_data：根据仪表盘名称和时间范围获取指定仪表盘的所有面板数据。
fetch_apm_metrics：根据指定的服务和时间范围，获取标准的 APM 指标（请求率、错误率、延迟、Apdex 等）。
fetch_services：从 Signoz 中获取所有已检测的服务，并可选择进行时间范围过滤。
execute_clickhouse_query：通过 Signoz API 执行自定义的 ClickHouse SQL 查询，支持时间范围。
execute_builder_query：执行 Signoz 构建器查询，用于自定义指标和聚合操作，支持时间范围。
fetch_traces_or_logs：使用 ClickHouse SQL 从 SigNoz 中获取跟踪或日志数据。需指定 data_type（'traces' 或 'logs'）、时间范围、服务名称和限制。返回跟踪或日志的表格结果。

🚀 快速开始

1. 获取 Signoz API 端点和（可选）API 密钥

确保你有一个正在运行的 Signoz 实例（自托管或云服务）。
（可选）如果你的 Signoz 实例的健康端点需要 API 密钥，请从 Signoz 用户界面生成或获取该密钥。

📦 安装指南

2A. 使用 uv 安装并运行（推荐用于本地开发）

2A.1. 使用 uv 安装依赖项

uv venv .venv
source .venv/bin/activate
uv sync

2A.2. 使用 uv 运行服务器

uv run -m src.signoz_mcp_server.mcp_server

你也可以根据需要使用 uv 运行其他入口脚本。
确保你的 config.yaml 文件与 mcp_server.py 文件在同一目录下，或者设置所需的环境变量（请参阅配置部分）。

2B. 使用 Docker Compose 运行（推荐用于生产/容器化环境）

使用你的 Signoz 详细信息（主机、API 密钥，如有需要）编辑 src/signoz_mcp_server/config.yaml 文件。
启动服务器：

docker-compose up -d

服务器默认将以 HTTP（SSE）模式在端口 8000 上运行。
你可以使用环境变量覆盖配置（见下文）。

🔧 技术细节

3. 配置

服务器按以下优先级顺序加载配置：

环境变量（推荐用于 Docker/CI）：
- SIGNOZ_HOST：Signoz 实例的 URL（例如 https://your-signoz-instance.com）
- SIGNOZ_API_KEY：Signoz API 密钥（可选）
- SIGNOZ_SSL_VERIFY：true 或 false（默认：true）
- MCP_SERVER_PORT：服务器运行的端口（默认：8000）
- MCP_SERVER_DEBUG：true 或 false（默认：true）
YAML 文件备用方案 (config.yaml)：

signoz:
  host: "https://your-signoz-instance.com"
  api_key: "your-signoz-api-key-here" # 可选
  ssl_verify: "true"
server:
  port: 8000
  debug: true

4. 与 AI 助手集成（例如，Claude Desktop、Cursor）

你可以将此 MCP 服务器与任何支持 MCP 协议的工具集成。以下是主要选项：

4A. 使用本地设置（使用 uv）

在本地运行服务器之前，安装依赖项并使用 uv 运行：

uv sync

然后将以下内容添加到你的客户端配置（例如，claude-desktop.json）：

{
  "mcpServers": {
    "signoz": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/full/path/to/signoz-mcp-server",
        "run",
        "src/signoz_mcp_server/mcp_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SIGNOZ_HOST": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-signoz-api-key-here",
        "SIGNOZ_SSL_VERIFY": "true"
      }
    }
  }
}

可以通过在 MacOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来找到 uv 的路径。
确保你的 config.yaml 文件与 mcp_server.py 文件在同一目录下，或者相应地更新路径。

4B. 使用 Docker Compose 或 Docker（使用环境变量，mcp - grafana 风格）

{
  "mcpServers": {
    "signoz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SIGNOZ_HOST",
        "-e",
        "SIGNOZ_API_KEY",
        "-e",
        "SIGNOZ_SSL_VERIFY",
        "ddroid/signoz-mcp-server",
        "-t",
        "stdio"
      ],
      "env": {
        "SIGNOZ_HOST": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-signoz-api-key-here",
        "SIGNOZ_SSL_VERIFY": "true"
      }
    }
  }
}

-t stdio 参数用于与 Docker MCP 客户端兼容（强制使用 stdio 握手模式）。
根据你的部署需求调整卷路径或环境变量。

4C. 连接到已运行的 MCP 服务器（HTTP/SSE）

如果你已经有一个 MCP 服务器在运行（例如，在远程主机、云虚拟机或 Kubernetes 上），你可以将你的 AI 助手或工具直接连接到其 HTTP 端点。

示例：Claude Desktop 或类似工具

{
  "mcpServers": {
    "signoz": {
      "url": "http://your-server-host:8000/mcp"
    }
  }
}

将 your-server-host 替换为你的 MCP 服务器实际运行的主机。
对于本地设置，使用 localhost 作为服务器主机（即 http://localhost:8000/mcp）。
对于本地或不安全的部署使用 http，对于生产或安全的部署使用 https。
确保服务器可以从你的客户端机器访问（检查防火墙、安全组等）。

示例：MCP 配置 YAML

mcp:
  endpoint: "http://your-server-host:8000/mcp"
  protocolVersion: "2025-06-18"

将 your-server-host 替换为你的 MCP 服务器实际运行的主机。
对于本地设置，使用 localhost 作为服务器主机（即 http://localhost:8000/mcp）。
根据你的 MCP 服务器部署方式，在 URL 模式中使用 http 或 https。
无需指定 command 或 args，只需指向 HTTP 端点。
这适用于任何支持通过 HTTP 进行 MCP 的工具或助手。
服务器必须以 HTTP（SSE）模式运行（此实现的默认模式）。

健康检查

curl http://localhost:8000/health

服务器默认在端口 8000 上运行。

📄 其他信息

需要帮助？加入我们的 Slack 社区并在 #mcp 频道留言。
想不进行设置就尝试？请遵循此文档在 DrDroid 云平台上快速开始。

signoz-mcp-server