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

配置設置

先決條件

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

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 兼容客戶端

使用場景

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

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