Grafana MCP Server 項目詳細介紹

項目概述

Grafana MCP Server 是一個基於模型上下文協議 (Model Context Protocol, MCP) 的伺服器，專為與 Grafana 實例及其周邊生態系統集成而設計。該項目為 AI 代理（如 Claude Desktop）提供了訪問和操作 Grafana 各種功能的能力。

核心功能特性

儀表板管理

• 搜索儀表板：快速檢索和定位特定的儀表板
• 獲取儀表板：通過 UID 獲取完整的儀表板配置
• 更新/創建儀表板：動態修改或創建新的儀表板（需要注意上下文窗口限制）

數據源集成

• 數據源管理：列出和獲取數據源信息
• 多數據源查詢支持：
  • Prometheus：執行 PromQL 查詢，獲取指標數據
  • Loki：執行 LogQL 查詢，檢索日誌數據
  • Tempo：分布式追蹤數據查詢
  • Pyroscope：性能分析數據查詢

元數據查詢

• Prometheus 元數據：獲取指標元數據、指標名稱、標籤名稱和標籤值
• Loki 元數據：獲取日誌標籤名稱、標籤值和統計信息

事件和告警管理

• 事件管理：搜索、創建、更新和關閉事件
• 告警規則：列出和獲取告警規則信息，獲取告警狀態
• 聯繫點管理：列出、創建和修改告警聯繫點

Grafana OnCall 集成

• 排班管理：列出和管理值班計劃
• 值班信息：獲取值班詳情和當前值班用戶
• 團隊和用戶管理：管理團隊和用戶信息
• 告警組管理：列出告警組

Sift 調查功能

• 智能調查：啟動 Sift 調查並查看結果
• 調查管理：創建、列出和獲取調查信息
• 分析功能：獲取調查分析結果
• 錯誤模式識別：在日誌中查找錯誤模式
• 性能分析：識別慢請求

工具配置

該項目提供了靈活的工具配置選項，您可以選擇啟用或禁用特定的功能類別：

工具名稱	分類	描述
search_dashboards	Search	搜索儀表板
get_dashboard_by_uid	Dashboard	通過 UID 獲取儀表板
update_dashboard	Dashboard	更新或創建新儀表板
list_datasources	Datasources	列出數據源
query_prometheus	Prometheus	執行 Prometheus 查詢
query_loki_logs	Loki	查詢和檢索日誌
list_incidents	Incident	列出事件
list_alert_rules	Alerting	列出告警規則
list_oncall_schedules	OnCall	列出 OnCall 排班計劃
find_error_pattern_logs	Sift	查找錯誤模式

使用 --disable-<category> 標誌可以禁用特定的工具類別。例如，使用 --disable-oncall 可以禁用 OnCall 相關工具。

安裝和配置

安裝方式

1. Docker 鏡像

docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana

2. 下載二進制文件

從 releases 頁面 下載最新版本並放置在 $PATH 目錄中。

3. 源码編譯

GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

配置設置

先決條件

1. 在 Grafana 中創建服務賬戶，並分配足夠的權限
2. 生成服務賬戶令牌

Claude Desktop 配置

使用二進制文件：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "--rm", "-p", "8000:8000",
        "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY",
        "mcp/grafana"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

調試模式

通過添加 -debug 標誌啟用調試模式，可以提供詳細的 HTTP 請求和響應日誌：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

開發和測試

開發環境設置

# 運行伺服器
make run

# 構建 Docker 鏡像
make build-image

# 運行 Docker 容器
docker run -it --rm -p 8000:8000 mcp-grafana:latest

測試類型

單元測試

make test-unit
# 或者
make test

集成測試

# 需要啟動 Docker 容器
make test-integration

雲測試

# 需要雲 Grafana 實例和憑證
make test-cloud

完整測試

# 啟動本地 Grafana 實例
docker-compose up -d

# 運行所有測試
make test-all

代碼質量

代碼檢查

make lint

JSON Schema 檢查

該項目包含自定義的 linter，用於檢查 jsonschema 結構標籤中未轉義的逗號：

make lint-jsonschema

技術架構

• 編程語言：Go
• 協議：Model Context Protocol (MCP)
• 通信方式：stdin/stdout 或 SSE (Server-Sent Events)
• 支持的客戶端：Claude Desktop 等 MCP 兼容客戶端

使用場景

1. AI 驅動的監控：讓 AI 代理能夠智能地查詢和分析監控數據
2. 自動化運維：通過 AI 自動創建和管理儀表板、告警規則
3. 智能事件響應：利用 AI 分析日誌和指標，快速定位和解決問題
4. 數據洞察：讓 AI 幫助從複雜的監控數據中提取有價值的信息

這個項目代表了 AI 與傳統監控工具集成的新趨勢，為開發者提供了一個強大的橋樑，連接人工智能助手和 Grafana 生態系統。