Signoz Mcp Server

Signoz MCP 服务

观看 Cursor 上的运行演示 📽️ 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 密钥

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

---

2. 安装与运行选项

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 运行（推荐用于生产环境/容器化环境）

1. 编辑 src/signoz_mcp_server/config.yaml，填写你的 Signoz 详细信息（主机地址，以及需要时的 API 密钥）。
2. 启动服务：

   docker-compose up -d
   

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

---

3. 配置

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

1. 环境变量（推荐用于 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）
2. YAML 文件回退配置（config.yaml）：

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

---

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

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

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

{
  "mcpServers": {
    "signoz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SIGNOZ_HOST",
        "-e",
        "SIGNOZ_API_KEY",
        "-e",
        "SIGNOZ_SSL_VERIFY",
        "drdroidlab/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 服务（例如，运行在远程主机、云 VM 或 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 schema 中使用 http 或 https。
• 无需指定 command 或 args——只需指向 HTTP 端点。
• 任何支持通过 HTTP 使用 MCP 的工具或助手都可以使用此配置。
• 服务必须以 HTTP（SSE）模式运行（这是此实现的默认模式）。

---

健康检查

curl http://localhost:8000/health

服务默认运行在 8000 端口。

---

5. 其他：

1. 需要帮助？加入我们的 Discord 社区，并在 #mcp 频道提问。
2. 想在不进行设置的情况下试用？请参阅此文档，快速开始使用 DrDroid 云平台。