Signoz MCP Server

🚀 Signoz MCP 服務器

觀看演示視頻 📽️ https://youtube.com/shorts/jxjmGyXXz7A

本 MCP 服務器解決了用戶與 Signoz 實例交互的難題，通過一系列工具，用戶可以方便地獲取 Signoz 中的各種數據，如儀表盤信息、APM 指標等，大大提升了數據獲取和處理的效率。

🚀 快速開始

1. 獲取 Signoz API 端點和（可選）API 密鑰

1. 確保你有一個正在運行的 Signoz 實例（自託管或雲服務）。
2. （可選）如果你的 Signoz 實例的健康端點需要 API 密鑰，請從 Signoz 界面生成或獲取該密鑰。

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. 使用你的 Signoz 詳細信息（主機、API 密鑰，如有需要）編輯 src/signoz_mcp_server/config.yaml 文件。
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" # 可選
  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 上運行。

5. 其他事項

1. 需要幫助？加入我們的 Slack 社區 並在 #mcp 頻道留言。
2. 想無需設置即可嘗試？請遵循此 文檔 在 DrDroid 雲平臺上快速開始。

✨ 主要特性

通過 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'）、時間範圍、服務名稱和限制。返回跟蹤或日誌的表格結果。