Grafana

官方

在您的 Grafana 實例中搜尋儀表板、調查事件並查詢資料來源

GitHub

3.3k

你可以用 Grafana MCP 做什麼？

Search and inspect dashboards — Ask to find dashboards by title, fetch a compact summary via get_dashboard_summary, or extract specific parts with get_dashboard_property using JSONPath.
Query datasources — Run PromQL against Prometheus, LogQL against Loki, or SQL against ClickHouse, Snowflake, Athena, and more, all through your Grafana instance.
Manage alerting — List alert rules and their statuses, create or update rules, and view notification policies and contact points.
Generate deeplinks — Create accurate URLs for dashboards, panels, and Explore views with time ranges and custom parameters, instead of guessing URLs.
Render dashboard images — Get a panel or full dashboard as a base64-encoded PNG, with options for dimensions, time range, and theme.
Manage incidents and on-call — Search and create incidents, view on-call schedules and current users, and list alert groups in Grafana OnCall.

文件

Grafana MCP server

一個用於 Grafana 的 Model Context Protocol (MCP) 伺服器。

這可讓您存取您的 Grafana 執行個體及其周邊生態系統。

快速開始

需要 uv。將以下內容新增至您的 MCP 用戶端設定（例如 Claude Desktop、Cursor）：

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

對於 Grafana Cloud，請將 GRAFANA_URL 替換為您的執行個體 URL（例如 https://myinstance.grafana.net）。請參閱 Usage 以了解更多安裝選項，包括 Docker、二進位檔和 Helm。

需求

需要 Grafana 9.0 或更新版本才能使用完整功能。某些功能，尤其是與資料來源相關的操作，可能因缺少 API 端點而無法在較早版本上正常運作。

功能

以下功能目前可在 MCP 伺服器中使用。此清單僅供參考，不代表路線圖或對未來功能的承諾。

儀表板

搜尋儀表板： 依標題或其他中繼資料尋找儀表板
依 UID 取得儀表板： 使用其唯一識別碼擷取完整的儀表板詳細資料。警告：大型儀表板可能消耗大量內容視窗空間。
取得儀表板摘要： 取得儀表板的精簡概覽，包括標題、面板數量、面板類型、變數和中繼資料，無需完整的 JSON，以最小化內容視窗使用量
取得儀表板屬性： 使用 JSONPath 表達式（例如 $.title、$.panels[*].title）擷取儀表板的特定部分，僅取得所需資料並減少內容視窗消耗
更新或建立儀表板： 修改現有儀表板或建立新儀表板。警告：需要完整的儀表板 JSON，可能消耗大量內容視窗空間。
修補儀表板： 無需完整 JSON 即可對儀表板套用特定變更，大幅減少針對性修改的內容視窗使用量
取得面板查詢和資料來源資訊： 從儀表板中的每個面板取得標題、查詢字串和資料來源資訊（包括 UID 和類型，如果有的話）

執行面板查詢

注意： 執行面板查詢工具預設為停用。若要啟用它們，請將 runpanelquery 新增至您的 --enabled-tools 旗標。

執行面板查詢： 使用自訂時間範圍和變數覆寫來執行儀表板面板的查詢。

內容視窗管理

儀表板工具現在包含多種策略，可有效管理內容視窗使用量（issue #101）：

使用 get_dashboard_summary 進行儀表板概覽和規劃修改
使用 get_dashboard_property 搭配 JSONPath，當您只需要特定的儀表板部分時
避免使用 get_dashboard_by_uid，除非您特別需要完整的儀表板 JSON

資料來源

列出並取得資料來源資訊： 檢視所有已設定的資料來源，並擷取每個資料來源的詳細資訊。
- 支援的資料來源類型：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch、OpenSearch、Snowflake、Athena。

查詢範例

注意： 查詢範例工具預設為停用。若要啟用它們，請將 examples 新增至您的 --enabled-tools 旗標。

取得查詢範例： 擷取不同資料來源類型的範例查詢，以學習查詢語法。

Prometheus 查詢

查詢 Prometheus： 對 Prometheus 資料來源執行 PromQL 查詢（支援即時和範圍指標查詢）。
查詢 Prometheus 中繼資料： 從 Prometheus 資料來源擷取指標中繼資料、指標名稱、標籤名稱和標籤值。
查詢直方圖百分位數： 使用 histogram_quantile 計算直方圖百分位數值（p50、p90、p95、p99）。

Loki 查詢

查詢 Loki 日誌和指標： 使用 LogQL 對 Loki 資料來源執行日誌查詢和指標查詢。
查詢 Loki 中繼資料： 從 Loki 資料來源擷取標籤名稱、標籤值和串流統計資料。
查詢 Loki 模式： 擷取 Loki 偵測到的日誌模式，以識別常見的日誌結構和異常。

InfluxDB 查詢

注意： InfluxDB 工具預設為停用。若要啟用它們，請將 influxdb 新增至您的 --enabled-tools 旗標。

查詢 InfluxDB： 使用 InfluxQL (v1.x) 或 Flux (v2.x) 對 InfluxDB 資料來源執行查詢。方言會從資料來源設定推斷，或可透過 dialect 參數明確設定。

ClickHouse 查詢

注意： ClickHouse 工具預設為停用。若要啟用它們，請將 clickhouse 新增至您的 --enabled-tools 旗標。

列出 ClickHouse 資料表： 列出 ClickHouse 資料庫中的所有資料表，包含列數和大小。
描述資料表結構： 取得 ClickHouse 資料表的欄位名稱、類型和中繼資料。
查詢 ClickHouse： 執行支援 Grafana 巨集和變數替換的 SQL 查詢。

CloudWatch 查詢

注意： CloudWatch 工具預設為停用。若要啟用它們，請將 cloudwatch 新增至您的 --enabled-tools 旗標。

列出 CloudWatch 命名空間： 探索可用的 AWS CloudWatch 命名空間。
列出 CloudWatch 指標： 列出特定命名空間中可用的指標。
列出 CloudWatch 維度： 取得用於篩選指標查詢的維度。
查詢 CloudWatch： 執行支援時間範圍的 CloudWatch 指標查詢。

Graphite 查詢

注意： Graphite 工具預設為停用。若要啟用它們，請將 graphite 新增至您的 --enabled-tools 旗標。

查詢 Graphite： 對 Graphite 資料來源執行 Graphite render API 查詢。
列出 Graphite 指標： 瀏覽和探索 Graphite 指標路徑。
列出 Graphite 標籤： 列出可用的 Graphite 標籤和標籤值。
查詢 Graphite 密度： 查詢給定模式的 Graphite 指標密度。

Athena 查詢

注意： Athena 工具預設為停用。若要啟用它們，請將 athena 新增至您的 --enabled-tools 旗標。

列出 Athena 目錄： 探索可用的資料目錄（例如 AwsDataCatalog、Iceberg 連接器）。
列出 Athena 資料庫： 列出 Athena 目錄中的資料庫。
列出 Athena 資料表： 列出 Athena 資料庫中的資料表。
描述 Athena 資料表： 取得 Athena 資料表的欄位名稱。
查詢 Athena： 透過 Grafana 對 Amazon Athena 執行 SQL 查詢，支援巨集替換、限制強制和範本變數。

Snowflake 查詢

注意： Snowflake 工具預設為停用。若要啟用它們，請將 snowflake 新增至您的 --enabled-tools 旗標。

查詢會透過 Grafana 的 Snowflake 資料來源（Grafana Enterprise 外掛程式 grafana-snowflake-datasource）進行，因此驗證由 Grafana 中的資料來源設定處理——MCP 伺服器永遠不會看到憑證。這與 ClickHouse 工具使用的模型相同。

列出 Snowflake 資料表： 透過 INFORMATION_SCHEMA.TABLES 探索資料表（包含資料庫、結構描述、種類、列數和大小）。可選的資料庫/結構描述篩選器。
描述資料表結構： 取得 Snowflake 資料表的欄位名稱、資料類型、可空性、預設值和註解。
查詢 Snowflake： 執行支援巨集和變數替換的 SQL 查詢。適用於查詢 Snowflake 的事件資料表（例如 SNOWFLAKE.TELEMETRY.EVENTS）以取得日誌和追蹤，或任何使用者資料表。
- 支援的巨集：$__timeFilter(column)、$__timeFrom、$__timeTo、$__from、$__to（Unix 毫秒）、$__interval（秒）、$__interval_ms，以及用於範本變數替換的 ${varname}。

Elasticsearch/OpenSearch 查詢

注意： Elasticsearch/OpenSearch 工具預設為停用。若要啟用它們，請將 elasticsearch 新增至您的 --enabled-tools 旗標。

查詢 Elasticsearch/OpenSearch： 使用 Lucene 查詢語法或 Elasticsearch Query DSL 對 Elasticsearch 或 OpenSearch 資料來源執行搜尋查詢。支援依時間範圍篩選，並擷取日誌、指標或任何已索引的資料。傳回包含索引、ID、來源欄位和可選相關性分數的文件。

Quickwit 查詢

注意： Quickwit 工具預設為停用。若要啟用它們，請將 quickwit 新增至您的 --enabled-tools 旗標。

查詢 Quickwit： 使用 Lucene 查詢語法或部分 Elasticsearch 相容的 Query DSL 對 Quickwit 資料來源執行搜尋查詢。支援依時間範圍篩選，並擷取日誌或其他已索引的文件。傳回包含索引、ID、來源欄位和可選相關性分數的文件。

Agent 可觀測性

注意： Agent 可觀測性工具預設為停用，且僅在 Grafana Cloud 中運作。若要啟用它們，請將 agento11y 新增至您的 --enabled-tools 旗標。

列出和搜尋對話： 列出最近的 LLM 對話，或使用篩選表達式（模型、提供者、agent、狀態、錯誤類型、評估結果等）在時間範圍內搜尋它們。搜尋結果包含錯誤計數、評分摘要、評估摘要和追蹤 ID。
取得對話詳細資料： 擷取單一對話及其所有生成內容，包括提示和輸出。
取得生成詳細資料和分數： 依 ID 擷取單一生成內容及其評估分數（評估器、分數鍵、值、是否通過、說明）。
讀取 agent 目錄： 列出傳送遙測資料的 agent，完整擷取單一 agent 版本（完整的系統提示、每個工具及其 JSON 結構描述，以及其執行的模型），瀏覽 agent 的版本歷史，並比較每個版本的評估分數彙總。有效版本是 sha256: 雜湊，工具變更永遠不會影響它們；對於未回報自身版本的 agent，它們會對系統提示進行雜湊，因此提示編輯會產生新版本。目錄和版本列帶有 token_estimate，在擷取完整提示之前值得檢查。
檢查評估器和範本： 讀取分數來源的評估器、它們衍生自的範本，以及可供 LLM 評判評估器使用的評判提供者和模型。啟用寫入工具後，也可以建立、分叉、測試和刪除評估器。
檢查評估規則和防護： 讀取將評估器綁定到生產流量的非同步評估規則，以及內聯執行且可以警告或拒絕的防護（掛鉤規則）。啟用寫入工具後，也可以建立、更新、預覽和刪除它們。寫入操作以及非持久性的 preview_rule 和 test_evaluator 操作需要 grafana-agento11y-app.eval:write 權限，該權限由 Agento11y Admin 角色授予。
管理已儲存的對話和集合： 讀取已儲存的對話（為對話提供穩定 ID、名稱和標籤的書籤）以及將它們分組的集合，包括每個集合的成員數量和每個已儲存對話列中嵌入的集合。啟用寫入工具後，也可以為對話加入書籤、建立和編輯集合，以及新增或移除成員。這些寫入操作需要相同的 grafana-agento11y-app.eval:write 權限。

Grafana Assistant

注意： Assistant 工具預設為停用，且需要在目標 Grafana 執行個體上安裝 Grafana Assistant 外掛程式（grafana-assistant-app）。它們也是寫入工具（assistant 可能變更堆疊狀態），因此在設定 --disable-write 時會跳過它們。若要啟用它們，請將 assistant 新增至您的 --enabled-tools 旗標。

詢問 assistant： 向 Grafana Assistant 傳送自然語言提示，並等待完整的文字回覆。Assistant 可能使用工具、指標、日誌和其他堆疊內容——比觸發單一隔離的資料來源查詢更廣泛。在後續呼叫中將傳回的 contextId 傳回，以繼續相同的對話。複雜任務可能需要數分鐘；呼叫會封鎖，直到回覆完成或請求逾時（5 分鐘）。

事件

搜尋、建立與更新事件： 在 Grafana Incident 中管理事件，包括搜尋、建立以及新增活動至事件。

Sift 調查

列出 Sift 調查： 取得 Sift 調查清單，支援 limit 參數。
取得 Sift 調查： 依 UUID 取得特定 Sift 調查的詳細資料。
取得 Sift 分析： 從 Sift 調查中取得特定分析。
在日誌中尋找錯誤模式： 使用 Sift 偵測 Loki 日誌中升高的錯誤模式。
尋找慢速請求： 使用 Sift (Tempo) 偵測慢速請求。

警示

列出並取得警示規則資訊： 在 Grafana 中檢視警示規則及其狀態（觸發中／正常／錯誤等）。同時支援 Grafana 管理的規則，以及來自 Prometheus 或 Loki 資料來源的資料來源管理規則。
建立與更新警示規則： 建立新的警示規則或修改現有規則。
刪除警示規則： 依 UID 移除警示規則。
管理警示路由： 檢視通知政策、聯絡點與時間間隔。同時支援 Grafana 管理的聯絡點，以及來自外部 Alertmanager 資料來源（Prometheus Alertmanager、Mimir、Cortex）的接收器。

Grafana OnCall

列出與管理值班表： 在 Grafana OnCall 中檢視與管理值班表。
取得值班詳細資料： 取得特定值班時段的詳細資訊。
取得目前值班使用者： 查看目前哪些使用者正在值班。
列出團隊與使用者： 檢視所有 OnCall 團隊與使用者。
列出警示群組： 依各種條件（包括狀態、整合、標籤與時間範圍）檢視與篩選 Grafana OnCall 的警示群組。
取得警示群組詳細資料： 依 ID 取得特定警示群組的詳細資訊。

管理

注意： 管理工具預設為停用。若要啟用，請在您的 --enabled-tools 旗標中包含 admin。

列出團隊： 檢視 Grafana 中所有已設定的團隊。
列出使用者： 檢視 Grafana 中組織內的所有使用者。
列出所有角色： 列出所有 Grafana 角色，可選擇篩選可委派角色。
取得角色詳細資料： 依 UID 取得特定 Grafana 角色的詳細資料。
列出角色的指派項目： 列出指派給某角色的所有使用者、團隊與服務帳戶。
列出使用者的角色： 列出指派給一個或多個使用者的所有角色。
列出團隊的角色： 列出指派給一個或多個團隊的所有角色。
列出資源的權限： 列出為特定資源（儀表板、資料來源、資料夾等）定義的所有權限。
描述 Grafana 資源： 列出某資源類型可用的權限與指派能力。

導覽

產生深層連結： 為 Grafana 資源建立準確的深層連結 URL，而非依賴 LLM 猜測 URL。
- 儀表板連結： 使用儀表板的 UID 產生直接連結（例如 http://localhost:3000/d/dashboard-uid）
- 面板連結： 使用 viewPanel 參數建立儀表板內特定面板的連結（例如 http://localhost:3000/d/dashboard-uid?viewPanel=5）
- Explore 連結： 產生 Grafana Explore 的連結，並預先設定資料來源（例如 http://localhost:3000/explore?left={"datasource":"prometheus-uid"}）
- 時間範圍支援： 在連結中加入時間範圍參數（from=now-1h&to=now）
- 自訂參數： 包含其他查詢參數，例如儀表板變數或重新整理間隔

註釋

取得註釋： 使用篩選條件查詢註釋。支援時間範圍、儀表板 UID、標籤與比對模式。
建立註釋： 在儀表板或面板上建立新的註釋。
建立 Graphite 註釋： 使用 Graphite 格式建立註釋（what、when、tags、data）。
更新註釋： 取代現有註釋的所有欄位（完整更新）。
修補註釋： 僅更新註釋的特定欄位（部分更新）。
取得註釋標籤： 列出可用的註釋標籤，可選擇篩選。

快照

列出快照： 列出儀表板快照，可選擇查詢與 limit 篩選條件。
取得快照： 依快照金鑰取得快照中繼資料與儀表板內容。
建立快照： 從完整的儀表板內容建立儀表板快照，可選擇到期時間與外部快照選項。
刪除快照： 依快照金鑰刪除快照。

渲染

取得面板或儀表板影像： 將 Grafana 儀表板面板或完整儀表板渲染為 PNG 影像。以 base64 編碼資料傳回影像，可用於報告、警示或簡報。支援自訂尺寸、時間範圍、主題、縮放比例與儀表板變數。也可透過選用的 provisioningPreview 參數，從佈建儲存庫分支（例如 git-sync PR 預覽）渲染尚未套用的儀表板。
- 注意：需要安裝並設定 Grafana Image Renderer 服務。

佈建

列出佈建儲存庫： 列出為此 Grafana 執行個體設定的佈建儲存庫（例如 git-sync 來源），傳回每個儲存庫的 slug 及其來源 URL、分支、路徑、同步狀態與健康狀態。
驗證佈建檔案： 在指定分支或提交上對佈建儲存庫中的檔案進行試跑套用。傳回該檔案是否會被接受、資源動作（建立／更新）、目標資源類型，以及任何結構化的驗證錯誤——與 Grafana 的 PR 評論器所使用的驗證介面相同。

工具清單是可設定的，因此您可以選擇要提供給 MCP 用戶端的工具。如果您不使用某些功能，或不想佔用太多上下文視窗，這會很有用。若要停用某類工具，請在啟動伺服器時使用 --disable-<category> 旗標。例如，若要停用 OnCall 工具，請使用 --disable-oncall；若要停用導覽深層連結產生功能，請使用 --disable-navigation。

RBAC 權限

每個工具都需要特定的 RBAC 權限才能正常運作。為 MCP 伺服器建立服務帳戶時，請根據您計畫使用的工具，確保其具備必要的權限。所列出的權限是最低要求的動作——您可能還需要適當的範圍（例如 datasources:*、dashboards:*、folders:*），視您的使用情境而定。

提示：如果您不熟悉 Grafana RBAC，或想要更快速、更簡單的設定方式，而不想設定許多細粒度的範圍，您可以將內建角色（例如 Editor）指派給服務帳戶。Editor 角色授予廣泛的讀寫存取權限，可允許大多數 MCP 伺服器操作；它比手動套用的範圍更不精細（因此限制較少），所以僅在便利性比嚴格的權限最小化更重要時使用。

注意： Grafana Incident 與 Sift 工具使用基本的 Grafana 角色，而非細粒度的 RBAC 權限：

檢視者角色： 唯讀操作所需（列出事件、取得調查）
編輯者角色： 寫入操作所需（建立事件、修改調查）

如需更多關於 Grafana RBAC 的資訊，請參閱官方文件。

RBAC 範圍

範圍定義權限所套用的特定資源。每個動作都需要適當的權限與範圍組合。

常見範圍模式：

廣泛存取： 使用 * 萬用字元進行組織範圍的存取
- datasources:* - 存取所有資料來源
- dashboards:* - 存取所有儀表板
- folders:* - 存取所有資料夾
- teams:* - 存取所有團隊
有限存取： 使用特定的 UID 或 ID 來限制對個別資源的存取
- datasources:uid:prometheus-uid - 僅存取特定的 Prometheus 資料來源
- dashboards:uid:abc123 - 僅存取 UID 為 abc123 的儀表板
- folders:uid:xyz789 - 僅存取 UID 為 xyz789 的資料夾
- teams:id:5 - 僅存取 ID 為 5 的團隊
- global.users:id:123 - 僅存取 ID 為 123 的使用者

範例：

完整的 MCP 伺服器存取： 為所有工具授予廣泛的權限

datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

有限的資料來源存取： 僅查詢特定的 Prometheus 與 Loki 執行個體

datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

特定儀表板存取： 僅讀取特定的儀表板

dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

工具

工具	類別	描述	所需的 RBAC 權限	所需的範圍
`list_teams`	管理	列出所有團隊	`teams:read`	`teams:*` 或 `teams:id:1`
`list_users_by_org`	管理	列出組織中的所有使用者	`users:read`	`global.users:*` 或 `global.users:id:123`
`list_all_roles`	管理	列出所有 Grafana 角色	`roles:read`	`roles:*`
`get_role_details`	管理	取得 Grafana 角色的詳細資訊	`roles:read`	`roles:uid:editor`
`get_role_assignments`	管理	列出角色的指派	`roles:read`	`roles:uid:editor`
`list_user_roles`	管理	列出使用者的角色	`roles:read`	`global.users:id:123`
`list_team_roles`	管理	列出團隊的角色	`roles:read`	`teams:id:7`
`get_resource_permissions`	管理	列出資源的權限	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	管理	描述 Grafana 資源類型	`permissions:read`	`dashboards:*`
`search_dashboards`	搜尋	搜尋儀表板	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_dashboard_by_uid`	儀表板	依 uid 取得儀表板	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	儀表板	更新或建立新的儀表板	`dashboards:create`、`dashboards:write`	`dashboards:`、`folders:` 或 `folders:uid:xyz789`
`get_dashboard_panel_queries`	儀表板	從儀表板取得面板標題、查詢、資料來源 UID 與類型	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	執行一個或多個儀表板面板查詢	`dashboards:read`、`datasources:query`	`dashboards:uid:`、`datasources:uid:`
`get_dashboard_property`	儀表板	使用 JSONPath 表達式擷取儀表板的特定部分	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	儀表板	取得儀表板的精簡摘要，不含完整 JSON	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	資料來源	列出資料來源	`datasources:read`	`datasources:*`
`get_datasource`	資料來源	依 UID 或名稱取得資料來源	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	範例*	取得資料來源類型的範例查詢	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	對 Prometheus 資料來源執行查詢	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	列出指標中繼資料	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	列出可用的指標名稱	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	列出符合選擇器的標籤名稱	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	列出特定標籤的值	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	計算直方圖百分位數值	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	事件	列出 Grafana Incident 中的事件	Viewer role	N/A
`create_incident`	事件	在 Grafana Incident 中建立事件	Editor role	N/A
`add_activity_to_incident`	事件	在 Grafana Incident 中為事件新增活動項目	Editor role	N/A
`get_incident`	事件	依 ID 取得單一事件	Viewer role	N/A
`query_loki_logs`	Loki	使用 LogQL 查詢與擷取日誌（日誌或指標查詢）	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	列出日誌中所有可用的標籤名稱	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	列出特定日誌標籤的值	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	取得日誌串流的統計資料	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	查詢偵測到的日誌模式以識別常見結構	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	稽核 Loki 標籤策略（即時或靜態），並可選擇診斷查詢效能	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	設定	產生強制執行已核准標籤的 Alloy `loki.process` 程式碼片段	N/A	N/A
`query_influxdb`	InfluxDB	使用 InfluxQL (v1) 或 Flux (v2) 查詢 InfluxDB	`datasources:query`	`datasources:uid:influxdb-uid`
`list_clickhouse_tables`	ClickHouse*	列出 ClickHouse 資料庫中的資料表	`datasources:query`	`datasources:uid:*`
`describe_clickhouse_table`	ClickHouse*	取得包含欄位類型的資料表結構	`datasources:query`	`datasources:uid:*`
`query_clickhouse`	ClickHouse*	使用巨集替換執行 SQL 查詢	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	列出可用的 AWS CloudWatch 命名空間	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	列出命名空間中的指標	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	列出指標的維度	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	執行 CloudWatch 指標查詢	`datasources:query`	`datasources:uid:*`
`list_athena_catalogs`	Athena*	列出可用的 Athena 資料目錄	`datasources:query`	`datasources:uid:*`
`list_athena_databases`	Athena*	列出 Athena 目錄中的資料庫	`datasources:query`	`datasources:uid:*`
`list_athena_tables`	Athena*	列出 Athena 資料庫中的資料表	`datasources:query`	`datasources:uid:*`
`describe_athena_table`	Athena*	取得 Athena 資料表的欄位名稱	`datasources:query`	`datasources:uid:*`
`query_athena`	Athena*	使用巨集替換執行 SQL 查詢	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	使用 Lucene 語法或 Query DSL 查詢 Elasticsearch 或 OpenSearch	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	使用 Lucene 語法或 Query DSL 查詢 Quickwit	`datasources:query`	`datasources:uid:quickwit-uid`
`list_snowflake_tables`	Snowflake*	透過 INFORMATION_SCHEMA 列出 Snowflake 資料庫/結構描述中的資料表	`datasources:query`	`datasources:uid:*`
`describe_snowflake_table`	Snowflake*	取得資料表結構描述（欄位型別、可空性、預設值、註解）	`datasources:query`	`datasources:uid:*`
`query_snowflake`	Snowflake*	使用巨集/變數替換執行 SQL 查詢	`datasources:query`	`datasources:uid:*`
`alerting_manage_rules`	Alerting	管理警示規則（列出、取得、版本、建立、更新、刪除）	`alert.rules:read` + `alert.rules:write` 用於變更操作	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	管理通知政策、聯絡點和時間間隔	`alert.notifications:read`	全域範圍
`list_oncall_schedules`	OnCall	從 Grafana OnCall 列出排班	`grafana-oncall-app.schedules:read`	外掛程式專屬範圍
`get_oncall_shift`	OnCall	取得特定 OnCall 班次的詳細資料	`grafana-oncall-app.schedules:read`	外掛程式專屬範圍
`get_current_oncall_users`	OnCall	取得目前特定排班中值班的使用者	`grafana-oncall-app.schedules:read`	外掛程式專屬範圍
`list_oncall_teams`	OnCall	從 Grafana OnCall 列出團隊	`grafana-oncall-app.user-settings:read`	外掛程式專屬範圍
`list_oncall_users`	OnCall	從 Grafana OnCall 列出使用者	`grafana-oncall-app.user-settings:read`	外掛程式專屬範圍
`list_alert_groups`	OnCall	從 Grafana OnCall 列出警示群組並提供篩選選項	`grafana-oncall-app.alert-groups:read`	外掛程式專屬範圍
`get_alert_group`	OnCall	依 ID 從 Grafana OnCall 取得特定警示群組	`grafana-oncall-app.alert-groups:read`	外掛程式專屬範圍
`get_sift_investigation`	Sift	依 UUID 擷取現有的 Sift 調查	檢視者角色	不適用
`get_sift_analysis`	Sift	從 Sift 調查中擷取特定分析	檢視者角色	不適用
`list_sift_investigations`	Sift	擷取 Sift 調查清單，可選擇設定數量上限	檢視者角色	不適用
`find_error_pattern_logs`	Sift	在 Loki 日誌中找出異常升高的錯誤模式。	編輯者角色	不適用
`find_slow_requests`	Sift	從相關的 tempo 資料來源中找出緩慢請求。	編輯者角色	不適用
`list_pyroscope_label_names`	Pyroscope	列出符合選擇器的標籤名稱	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	列出符合選擇器的標籤值（針對特定標籤名稱）	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	列出可用的剖析類型	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	從 Pyroscope 查詢剖析資料、指標，或兩者	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	取得指定實體的斷言摘要	外掛程式專屬權限	外掛程式專屬範圍
`agento11y_manage_conversations`	Agent Observability*	從 Grafana Agent Observability 列出、搜尋和擷取 LLM 對話	`grafana-agento11y-app.conversations:read`	不適用
`agento11y_manage_generations`	Agent Observability*	從 Grafana Agent Observability 擷取 LLM 生成詳細資料和評估分數	`grafana-agento11y-app.data:read`	不適用
`agento11y_manage_agents`	Agent Observability*	讀取代理程式目錄：列出代理程式、完整取得某個代理程式版本、列出版本歷史記錄，以及各版本的評分彙總	`grafana-agento11y-app.data:read`	不適用
`agento11y_manage_evaluators`	Agent Observability*	管理評估器、評估器範本和評審目錄（列出、取得、更新插入、分叉、測試、刪除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用於變更操作和測試	不適用
`agento11y_manage_eval_rules`	Agent Observability*	管理評估規則和防護（列出、取得、建立、更新、預覽、刪除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用於變更操作和預覽	不適用
`agento11y_manage_eval_collections`	Agent Observability*	管理已儲存的對話及其分組集合（列出、取得、儲存、建立、更新、刪除、新增和移除成員）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用於變更操作	不適用
`ask_assistant`	Assistant*	傳送提示詞給 Grafana Assistant 並傳回完整文字回覆（透過 `contextId` 進行多輪對話）	外掛程式專屬權限	外掛程式專屬範圍
`generate_deeplink`	Navigation	為 Grafana 資源產生精確的深層連結 URL	無（唯讀 URL 產生）	不適用
`get_annotations`	Annotations	使用篩選條件擷取註解	`annotations:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	Annotations	建立新的註解（標準或 Graphite 格式）	`annotations:write`	`annotations:*`
`update_annotation`	Annotations	更新註解的特定欄位（部分更新）	`annotations:write`	`annotations:*`
`get_annotation_tags`	註解	列出註解標籤，可選過濾條件	`annotations:read`	`annotations:*`
`list_snapshots`	快照	列出儀表板快照，可選查詢和限制過濾	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`get_snapshot`	快照	依快照金鑰取得快照中繼資料和儀表板內容	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`create_snapshot`	快照	從完整的儀表板內容建立儀表板快照	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`delete_snapshot`	快照	依快照金鑰刪除儀表板快照	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`get_panel_image`	渲染	將儲存的儀表板或面板——或從儲存庫分支的佈建預覽——渲染為 PNG 影像	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	佈建	列出佈建儲存庫（例如 git-sync 來源），包含其來源 URL、分支、同步狀態和健康狀態	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	佈建	試運行套用佈建儲存庫中的檔案，並回報准入驗證錯誤	`provisioning.repositories:read`	N/A
* 預設停用。將類別加入 `--enabled-tools` 以啟用。

CLI 旗標參考

mcp-grafana 二進位檔支援各種命令列旗標以供設定：

傳輸選項：

-t, --transport：傳輸類型（stdio、sse 或 streamable-http）— 預設：stdio
--address：SSE/streamable-http 伺服器的主機與連接埠 — 預設：localhost:8000
--base-path：SSE/streamable-http 伺服器的基礎路徑
--endpoint-path：streamable-http 伺服器的端點路徑 — 預設：/mcp

HTTP 傳輸安全性（僅限 SSE / streamable-http）：

Host/Origin 驗證會在監聽器的每個路由上強制執行 — /sse、/mcp、/healthz 和 /metrics — 因此 DNS 重新綁定的瀏覽器無法觸及任何一個。Stdio 傳輸不受影響。

--allowed-hosts：Host 標頭值的逗號分隔允許清單。預設為 --address 的 loopback 變體（例如 localhost:8000,127.0.0.1:8000,[::1]:8000）。解析為空的值（未設定、,、, 等）也會回退到預設值，因此拼寫錯誤不會悄悄停用檢查。帶有允許清單之外的 Host 標頭的請求會以 403 拒絕。傳入 * 可停用檢查 — 僅在執行於會重寫 Host 的可信反向代理之後，或位於隔離網路中時才安全。K8s httpGet 探測和外部 /metrics 抓取需要此清單中的明確主機名稱、*，或 tcpSocket 探測／獨立指標連接埠（--metrics-address）。
--allowed-origins：Origin 標頭值的逗號分隔允許清單。預設為空 — 任何帶有 Origin 標頭的請求都會被拒絕（瀏覽器對跨來源請求總是會傳送一個，且不應有任何瀏覽器直接呼叫此伺服器）。設定為明確清單以允許基於瀏覽器的用戶端，或設定 * 以停用檢查。

除錯與記錄：

--debug：啟用除錯模式以進行詳細的 HTTP 請求／回應記錄
--log-level：記錄層級（debug、info、warn、error）— 預設：info

Grafana 用戶端選項：

--grafana-timeout：Grafana 用戶端發出請求的時間限制。接受 Go 持續時間字串（例如 10s、500ms）— 預設：10s
--include-args-in-spans：在 OpenTelemetry spans 中包含工具呼叫引數。僅在非生產環境或已知引數不含 PII 時啟用 — 預設：false

可觀測性：

--metrics：在 /metrics 啟用 Prometheus 指標端點
--metrics-address：指標伺服器的獨立位址（例如 :9090）。若為空，指標將在主伺服器上提供
--slow-request-threshold：當任何 MCP 請求（工具呼叫、清單、資源讀取等）花費超過此持續時間時記錄事件。接受 Go 持續時間字串（例如 500ms、5s）。預設 0 停用慢請求記錄。請參閱慢請求記錄一節。
--slow-request-log-level：慢請求事件的記錄層級（info 或 warn）— 預設：warn。

工作階段管理：

--session-idle-timeout-minutes：工作階段閒置逾時（分鐘）。在此期間內無活動的工作階段會自動回收 — 預設：30。設定為 0 以停用工作階段回收。僅與 SSE 和 streamable-http 傳輸相關。

工具設定：

--enabled-tools：啟用類別的逗號分隔清單 — 預設：除 admin、agento11y、assistant、athena、clickhouse、cloudwatch、elasticsearch、examples、graphite、quickwit、runpanelquery 和 snowflake 之外的所有類別。若要啟用已停用的類別，請將它們加入清單（例如 "search,datasource,...,snowflake"）
--max-loki-log-limit：每次 query_loki_logs 呼叫傳回的日誌行數上限 — 預設：100。注意：請將此值設定為至少低於 Loki 伺服器端 max_entries_limit_per_query 1，以允許截斷偵測（工具會在內部請求 limit+1 以偵測是否還有更多資料）。
--disable-search：停用搜尋工具
--disable-datasource：停用資料來源工具
--disable-incident：停用事件工具
--disable-prometheus：停用 Prometheus 工具
--disable-write：停用寫入工具（建立／更新操作）
--disable-loki：停用 Loki 工具
--disable-elasticsearch：停用 Elasticsearch 和 OpenSearch 工具
--disable-quickwit：停用 Quickwit 工具
--disable-influxdb：停用 InfluxDB 工具
--disable-alerting：停用警示工具
--disable-dashboard：停用儀表板工具
--disable-oncall：停用 OnCall 工具
--disable-asserts：停用 Asserts 工具
--disable-sift：停用 Sift 工具
--disable-admin：停用管理工具
--disable-pyroscope：停用 Pyroscope 工具
--disable-navigation：停用導覽工具
--disable-rendering：停用渲染工具（面板／儀表板影像匯出）
--disable-snapshot：停用快照工具
--disable-cloudwatch：停用 CloudWatch 工具
--disable-examples：停用查詢範例工具
--disable-clickhouse：停用 ClickHouse 工具
--disable-snowflake：停用 Snowflake 工具
--disable-runpanelquery：停用執行面板查詢工具
--disable-graphite：停用 Graphite 工具
--disable-athena：停用 Athena 工具
--disable-provisioning：停用佈建工具
--disable-agento11y：停用 Agent Observability 工具
--disable-assistant：停用 Grafana Assistant 工具

唯讀模式

--disable-write 旗標提供以唯讀模式執行 MCP 伺服器的方式，防止對您的 Grafana 執行個體進行任何寫入操作。這在您想要提供安全唯讀存取的情境中很有用，例如：

使用具有有限唯讀權限的服務帳戶
為 AI 助理提供可觀測性資料而不具修改能力
在應限制寫入存取的生產環境中執行
在您想要防止意外修改的測試和開發情境中

啟用 --disable-write 時，下列寫入操作會被停用：

儀表板工具：

update_dashboard

資料夾工具：

create_folder

事件工具：

create_incident
add_activity_to_incident

警示工具：

alerting_manage_rules（建立、更新、刪除操作）

註釋工具：

create_annotation
update_annotation

Sift 工具：

find_error_pattern_logs（建立調查）
find_slow_requests（建立調查）

快照工具：

create_snapshot
delete_snapshot

Agent Observability 工具：

agento11y_manage_evaluators（upsert、刪除、fork、測試評估器操作）
agento11y_manage_eval_rules（建立、更新、刪除、預覽規則和防護操作）
agento11y_manage_eval_collections（儲存和刪除已儲存的對話；建立、更新、刪除集合；新增和移除集合成員）

所有讀取操作仍然可用，讓您可以查詢儀表板、執行 PromQL/LogQL 查詢、列出資源和擷取資料。

用戶端 TLS 設定（用於 Grafana 連線）：

--tls-cert-file：用戶端驗證的 TLS 憑證檔案路徑
--tls-key-file：用戶端驗證的 TLS 私密金鑰檔案路徑
--tls-ca-file：伺服器驗證的 TLS CA 憑證檔案路徑
--tls-skip-verify：跳過 TLS 憑證驗證（不安全）

伺服器 TLS 設定（僅限 streamable-http 傳輸）：

--server.tls-cert-file：伺服器 HTTPS 的 TLS 憑證檔案路徑
--server.tls-key-file：伺服器 HTTPS 的 TLS 私密金鑰檔案路徑

使用方式

此 MCP 伺服器可與本機 Grafana 執行個體和 Grafana Cloud 搭配使用。對於 Grafana Cloud，請在下方設定範例中使用您的執行個體 URL（例如 https://myinstance.grafana.net）而非 http://localhost:3000。

如果使用服務帳戶權杖驗證，請在 Grafana 中建立具有足夠權限以使用您想使用之工具的服務帳戶，產生服務帳戶權杖，並將其複製到剪貼簿以在設定檔中使用。有關建立服務帳戶權杖的詳細資訊，請參閱 Grafana 服務帳戶文件。提示：如果您不想設定細粒度的 RBAC 範圍，一個更簡單（但限制較少）的選項是將內建的 Editor 角色指派給服務帳戶。這會授予涵蓋大多數 MCP 伺服器操作的廣泛讀寫存取權 — 在便利性重於嚴格最小權限需求時使用它。

注意： 環境變數 GRAFANA_API_KEY 已棄用，將在未來版本中移除。請改用 GRAFANA_SERVICE_ACCOUNT_TOKEN。舊的變數名稱將繼續用於向後相容，但會顯示棄用警告。

從檔案讀取服務帳戶權杖

與其透過 GRAFANA_SERVICE_ACCOUNT_TOKEN 內嵌傳遞權杖，您可以將 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE 指向包含權杖的檔案路徑。檔案會在每次請求時重新讀取，因此輪換的權杖會自動被擷取，無需重新啟動伺服器。

這在 Kubernetes 中特別有用，當底層 Secret 變更時，掛載為磁碟區的 Secret 會就地更新（通常約 1 分鐘內）。結合以權杖值為鍵的每次請求用戶端快取，輪換的權杖會透明地產生新的用戶端，無需 pod 重新啟動且無停機時間：

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

檔案內容的周圍空白（包括尾端換行）會被去除。如果同時設定了 GRAFANA_SERVICE_ACCOUNT_TOKEN 和 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE，內嵌權杖優先。

多組織支援

您可以使用下列任一方式指定要互動的組織：

環境變數： 將 GRAFANA_ORG_ID 設定為數值組織 ID
HTTP 標頭： 使用 SSE 或 streamable HTTP 傳輸時設定 X-Grafana-Org-Id（標頭優先於環境變數 — 這表示您也可以設定預設組織）。

提供組織 ID 時，MCP 伺服器會在對 Grafana 的所有請求上設定 X-Grafana-Org-Id 標頭，確保操作在指定的組織內容中執行。

含組織 ID 的範例：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

自訂 HTTP 標頭

您可以使用 GRAFANA_EXTRA_HEADERS 環境變數將任意 HTTP 標頭加入所有 Grafana API 請求。值應為將標頭名稱對應到值的 JSON 物件。

含自訂標頭的範例：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

從用戶端轉送標頭（僅限 SSE/Streamable-HTTP）

當 MCP 伺服器在處理 SSO 的閘道或反向代理之後執行（例如具有 OIDC 的 AWS ALB）時，每個使用者的工作階段 cookie 必須到達 Grafana，以便將請求與已驗證的使用者關聯。GRAFANA_FORWARD_HEADERS 環境變數透過指定要從傳入 HTTP 請求複製到每個傳出 Grafana API 請求的標頭名稱逗號分隔允許清單來啟用此功能。

這僅適用於使用 SSE（-t sse）或 streamable-http（-t streamable-http）傳輸時。在 stdio 模式下無效。

範例：轉送工作階段 cookie

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

您可以透過以逗號分隔來轉送多個標頭：

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

轉送的標頭會與 GRAFANA_EXTRA_HEADERS 中定義的任何標頭合併。如果標頭名稱同時出現在兩者中，則該請求的傳入請求值優先。

您有幾個安裝 mcp-grafana 的選項：
- uvx（建議）：如果您已安裝 uv，則無需額外設定 — uvx 會自動下載並執行伺服器：
```
uvx mcp-grafana
```

Docker 映像檔：使用 Docker Hub 上預先建置好的 Docker 映像檔。

重要：Docker 映像檔的 entrypoint 預設設定為以 SSE 模式執行 MCP 伺服器，但大多數使用者會希望使用 STDIO 模式，以便與 Claude Desktop 等 AI 助理直接整合：

STDIO 模式：若要使用 stdio 模式，您必須使用 -t stdio 明確覆寫預設值，並加入 -i 旗標以保持 stdin 開啟：

docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

SSE 模式：在此模式下，伺服器會以 HTTP 伺服器形式執行，供用戶端連線。您必須使用 -p 旗標開放連接埠 8000：

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana

Streamable HTTP 模式：在此模式下，伺服器會以獨立程序形式運作，可處理多個用戶端連線。您必須使用 -p 旗標開放連接埠 8000：在此模式下，您必須使用 -t streamable-http 明確覆寫預設值

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t streamable-http

若要在 HTTPS streamable HTTP 模式下使用伺服器 TLS 憑證：

docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

下載二進位檔：從發行頁面下載 mcp-grafana 的最新版本，並將其放入您的 $PATH。
從原始碼建置：如果您已安裝 Go 工具鏈，也可以從原始碼建置並安裝，使用 GOBIN 環境變數來指定二進位檔的安裝目錄。此目錄也應位於您的 $PATH 中。
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```

使用 Helm 部署至 Kubernetes：使用 Grafana helm-charts 儲存庫中的 Helm chart

helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

將伺服器設定新增至您的用戶端設定檔。例如，以 Claude Desktop 為例：

如果使用 uvx：

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

如果使用二進位檔：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

注意：如果您在 Claude Desktop 中看到 Error: spawn mcp-grafana ENOENT，則需要指定 mcp-grafana 的完整路徑。

如果使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

注意：-t stdio 參數在此至關重要，因為它會覆寫 Docker 映像檔中的預設 SSE 模式。

搭配遠端 MCP 伺服器使用 VSCode

如果您使用 VSCode 並以 SSE 模式執行 MCP 伺服器（這是使用 Docker 映像檔且未覆寫傳輸方式時的預設模式），請確保您的 .vscode/settings.json 包含以下內容：

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

若要在 HTTPS streamable HTTP 模式下使用伺服器 TLS 憑證：

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

除錯模式

您可以透過在命令中加入 -debug 旗標，為 Grafana 傳輸啟用除錯模式。這將提供 MCP 伺服器與 Grafana API 之間 HTTP 請求和回應的詳細記錄，有助於疑難排解。

若要搭配 Claude Desktop 設定使用除錯模式，請更新您的設定如下：

如果使用二進位檔：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

如果使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

注意：與標準設定相同，-t stdio 參數是覆寫 Docker 映像檔中預設 SSE 模式所必需的。

TLS 設定

如果您的 Grafana 執行個體位於 mTLS 之後，或需要自訂 TLS 憑證，您可以設定 MCP 伺服器使用自訂憑證。伺服器支援下列 TLS 設定選項：

--tls-cert-file：用於用戶端驗證的 TLS 憑證檔案路徑
--tls-key-file：用於用戶端驗證的 TLS 私密金鑰檔案路徑
--tls-ca-file：用於伺服器驗證的 TLS CA 憑證檔案路徑
--tls-skip-verify：略過 TLS 憑證驗證（不安全，僅供測試使用）

使用用戶端憑證驗證的範例：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

使用 Docker 的範例：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

TLS 設定會套用至 MCP 伺服器使用的所有 HTTP 用戶端，包括：

主要的 Grafana OpenAPI 用戶端
Prometheus 資料來源用戶端
Loki 資料來源用戶端
Incident 管理用戶端
Sift 調查用戶端
Alerting 用戶端
Asserts 用戶端

直接 CLI 使用範例：

使用自簽憑證進行測試：

./mcp-grafana --tls-skip-verify -debug

使用用戶端憑證驗證：

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

僅使用自訂 CA 憑證：

./mcp-grafana --tls-ca-file /path/to/ca.crt

程式化使用：

如果您以程式化方式使用此程式庫，也可以建立啟用 TLS 的 context 函式：

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

自行架設 HTTP 伺服器時的 URL 驗證：

當程式庫使用者將 mcp-grafana 的 context 函式整合到自己的 http.Server 時，請安裝 ValidateGrafanaURLMiddleware 以拒絕格式錯誤的 X-Grafana-URL 標頭並回傳 400 Bad Request（與二進位檔的行為一致）：

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

當直接呼叫 NewGrafanaClient 時（stdio 或程式化建構），請預先驗證不受信任的 URL，以避免可觸及的 panic：

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

兩種模式都共用 ValidateGrafanaURL 作為單一驗證器。

伺服器 TLS 設定（僅限 Streamable HTTP 傳輸）

使用 streamable HTTP 傳輸（-t streamable-http）時，您可以設定 MCP 伺服器提供 HTTPS 而非 HTTP。當您需要保護 MCP 用戶端與伺服器本身之間的連線時，這非常有用。

伺服器針對 streamable HTTP 傳輸支援下列 TLS 設定選項：

--server.tls-cert-file：伺服器 HTTPS 的 TLS 憑證檔案路徑（TLS 必填）
--server.tls-key-file：伺服器 HTTPS 的 TLS 私密金鑰檔案路徑（TLS 必填）

注意：這些旗標與上述用戶端 TLS 旗標完全分開。用戶端 TLS 旗標設定 MCP 伺服器如何連線至 Grafana，而這些伺服器 TLS 旗標則設定用戶端在使用 streamable HTTP 傳輸時如何連線至 MCP 伺服器。

使用 HTTPS streamable HTTP 伺服器的範例：

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

這將在 HTTPS 連接埠 8443 上啟動 MCP 伺服器。用戶端接著會連線至 https://localhost:8443/ 而非 http://localhost:8000/。

使用伺服器 TLS 的 Docker 範例：

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

健康檢查端點

使用 SSE（-t sse）或 streamable HTTP（-t streamable-http）傳輸時，MCP 伺服器會在 /healthz 公開健康檢查端點。此端點可供負載平衡器、監控系統或編排平台用來驗證伺服器是否正在執行並接受連線。

端點： GET /healthz

回應：

狀態碼：200 OK
回應主體：ok

使用範例：

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# With custom address
curl http://localhost:9090/healthz

注意： 健康檢查端點僅在使用 SSE 或 streamable HTTP 傳輸時可用。使用 stdio 傳輸（-t stdio）時無法使用，因為 stdio 不會公開 HTTP 伺服器。

可觀測性

MCP 伺服器支援 Prometheus 指標、OpenTelemetry 分散式追蹤，以及 OpenTelemetry 日誌匯出，遵循 OTel MCP 語意慣例。追蹤和日誌匯出透過標準的 OTEL_* 環境變數設定，並可搭配任何傳輸方式使用。

注意： mcp-grafana 目前僅支援 OTLP/gRPC 傳輸來傳送追蹤和日誌。OTEL_EXPORTER_OTLP_PROTOCOL（及其 _TRACES_PROTOCOL / _LOGS_PROTOCOL 變體）不會被採用——一律使用 gRPC。

指標

使用 SSE 或 streamable HTTP 傳輸時，可使用 --metrics 旗標啟用 Prometheus 指標：

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

可用指標：

指標	類型	說明
`mcp_server_operation_duration_seconds`	Histogram	MCP 作業的持續時間（標籤：`mcp_method_name`、`gen_ai_tool_name`、`error_type`、`network_transport`、`mcp_protocol_version`）
`mcp_server_session_duration_seconds`	Histogram	MCP 用戶端工作階段的持續時間（標籤：`network_transport`、`mcp_protocol_version`）
`http_server_request_duration_seconds`	Histogram	HTTP 伺服器請求的持續時間（來自 otelhttp）

注意： 指標僅在使用 SSE 或 streamable HTTP 傳輸時可用。stdio 傳輸不提供指標。

慢請求記錄

--slow-request-threshold 旗標會在 MCP 請求（工具呼叫、清單、資源讀取等）超過指定持續時間時，發出結構化的日誌事件。這對於診斷慢速查詢和工具呼叫非常有用，而不會被完整的除錯日誌淹沒。

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

日誌事件攜帶下列結構化屬性：

屬性	說明
`mcp.method`	MCP 方法（例如 `tools/call`、`tools/list`、`resources/read`）
`duration`	觀察到的請求持續時間
`threshold`	設定的閾值
`tool`	工具名稱（僅存在於 `tools/call` 方法中）
`error`	請求失敗時的錯誤值（盡力而為的內容；內容由上游錯誤包裝控制）
`error.type`	有界基數的錯誤分類（未型別錯誤使用 `_OTHER`）

慢請求記錄適用於所有傳輸方式（包括 stdio），且不需要 --metrics。預設閾值 0 會完全停用此功能。代理工具會流經 tools/call 並自動涵蓋在內。

追蹤

分散式追蹤透過標準的 OTEL_* 環境變數設定，且獨立於 --metrics 旗標運作。當設定 OTEL_EXPORTER_OTLP_ENDPOINT（或訊號特定的 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT）時，伺服器會透過 OTLP/gRPC 匯出追蹤：

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

工具呼叫 span 遵循 semconv 命名（tools/call <tool_name>），並包含 gen_ai.tool.name、mcp.method.name 和 mcp.session.id 等屬性。伺服器也支援從工具呼叫請求的 _meta 欄位進行 W3C trace context 傳播。

日誌

當設定 OTEL_EXPORTER_OTLP_ENDPOINT（或訊號特定的 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT）時，伺服器除了現有的純文字 stderr 輸出外，也會透過 OTLP/gRPC 匯出結構化日誌。otelslog bridge 會自動從作用中的 span 附加 trace_id 和 span_id，因此日誌記錄會與伺服器已發出的追蹤相互關聯。

追蹤和日誌會獨立解析其端點，因此兩個訊號可以分別啟用：僅設定 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 會啟用追蹤但不會匯出日誌，僅設定 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 會啟用日誌匯出但不會追蹤，而通用的 OTEL_EXPORTER_OTLP_ENDPOINT 則會同時啟用兩者。

如果您使用通用的 OTEL_EXPORTER_OTLP_ENDPOINT 但想要停用日誌匯出（例如您的後端不支援 LogsService），請設定：

OTEL_LOGS_EXPORTER=none

這會防止伺服器建立 OTLP 日誌匯出器，無論端點設定為何，都能避免 unknown service opentelemetry.proto.collector.logs.v1.LogsService 之類的錯誤。

啟用 OTLP 日誌時，stderr 記錄保持不變；您可以繼續依賴容器日誌，或視需要將 stderr 導向 /dev/null。

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

傳輸方式為 OTLP/gRPC（預設連接埠 4317）。日誌可以直接傳送至任何接受 OTLP/gRPC 的受管後端——例如 Grafana Cloud——方法是將 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT（或通用的 OTEL_EXPORTER_OTLP_ENDPOINT）指向遠端 gRPC 端點，並透過 OTEL_EXPORTER_OTLP_LOGS_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）提供驗證，與上述追蹤範例相同。本機 OTel collector 是選用的——對於扇出、批次處理或多後端路由很有用，但並非必要。

訊號特定的變體 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT、OTEL_EXPORTER_OTLP_LOGS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_INSECURE、OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE、OTEL_EXPORTER_OTLP_LOGS_TIMEOUT 和 OTEL_EXPORTER_OTLP_LOGS_COMPRESSION 會被採用，並覆寫其通用的 OTEL_EXPORTER_OTLP_* 對應項目——完整清單和優先順序規則請參閱 OTel exporter 規格。

如果設定的 collector 無法連線，日誌記錄會緩衝在記憶體中（預設佇列：2048），一旦佇列填滿，最舊的記錄會被丟棄。程序會繼續執行，不會阻斷服務。如果您需要在停機期間進行無損緩衝，請設定本機 OTel collector。

日誌也會在 stdio 傳輸下匯出，這使得集中管理 IDE 用戶端所呼叫的本機 mcp-grafana 執行個體日誌變得容易。

包含指標、追蹤和日誌的 Docker 範例：

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

疑難排解

Grafana 版本相容性

如果您在使用資料來源相關工具時遇到以下錯誤：

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

這通常表示您使用的 Grafana 版本早於 9.0。/datasources/uid/{uid} API 端點是在 Grafana 9.0 中引入的，在較早版本上，資料來源操作將會失敗。

解決方法： 將您的 Grafana 執行個體升級至 9.0 或更高版本即可解決此問題。

開發

歡迎貢獻！如果您有任何建議或改進，請開啟 issue 或提交 pull request。

此專案以 Go 撰寫。請依照您平台的說明安裝 Go。

若要在本機以 STDIO 模式執行伺服器（這是本機開發的預設模式），請使用：

make run

若要在本機以 SSE 模式執行伺服器，請使用：

go run ./cmd/mcp-grafana --transport sse

您也可以在自訂建置的 Docker 映像檔中使用 SSE 傳輸來執行伺服器。與已發佈的 Docker 映像檔一樣，此自訂映像檔的進入點預設為 SSE 模式。若要建置映像檔，請使用：

make build-image

若要以 SSE 模式（預設）執行映像檔，請使用：

docker run -it --rm -p 8000:8000 mcp-grafana:latest

如果您需要改以 STDIO 模式執行，請覆寫傳輸設定：

docker run -it --rm mcp-grafana:latest -t stdio

測試

共有三種類型的測試可用：

單元測試（不需要外部相依性）：

make test-unit

您也可以使用以下指令執行單元測試：

make test

整合測試（需要 Docker 容器已啟動並執行中）：

make test-integration

雲端測試（需要雲端 Grafana 執行個體和憑證）：

make test-cloud

注意：雲端測試會在 CI 中自動設定。對於本機開發，您需要自行設定 Grafana Cloud 執行個體和憑證。

更全面的整合測試需要 Grafana 執行個體在本機連接埠 3000 上執行；您可以使用 Docker Compose 啟動一個：

docker-compose up -d

整合測試可以使用以下指令執行：

make test-all

如果您要新增更多工具，請為它們加入整合測試。現有的測試應該是不錯的起點。

程式碼檢查

若要檢查程式碼，請執行：

make lint

這包含一個自訂 linter，用於檢查 jsonschema struct 標籤中未跳脫的逗號。description 欄位中的逗號必須使用 \\, 跳脫，以防止靜默截斷。您可以僅執行此 linter：

make lint-jsonschema

更多詳細資訊請參閱 JSONSchema Linter 文件。

授權

此專案採用 Apache 授權條款 2.0 版授權。