Grafana

官方

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

GitHub

3.5k

試用此 MCP贊助

你可以用 Grafana MCP 做什麼？

搜尋與檢視儀表板 — 依標題、資料夾、標籤或星號狀態尋找儀表板，然後擷取摘要或特定 JSONPath 屬性，以減少上下文使用量。
查詢可觀測性資料 — 直接對已設定的資料來源執行 PromQL、LogQL、SQL、CloudWatch、Graphite、Elasticsearch 或 InfluxDB 查詢。
管理警示與事件 — 建立、更新與刪除警示規則，檢視觸發狀態，並管理 Grafana Incident 記錄（包括自訂欄位）。
渲染儀表板影像 — 為面板或完整儀表板產生 PNG 快照，可自訂時間範圍、主題與尺寸，用於報告或警示。
產生精確的深層連結 — 建立指向儀表板、面板或 Explore 檢視的直接 URL，並附上正確的時間範圍與參數，而非猜測 URL。
管理註解與快照 — 建立、更新、修補或刪除註解，並列出或建立具到期選項的儀表板快照。

文件

Grafana MCP 伺服器

一個用於 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、標籤或星號狀態尋找儀表板
依 UID 取得儀表板： 使用其唯一識別碼擷取完整的儀表板詳細資料。傳入可選的 version 以載入已儲存的快照，而非目前的儀表板。警告：大型儀表板可能消耗大量上下文視窗空間。
列出儀表板版本： 以精簡中繼資料（版本號碼、作者、時間戳記、儲存訊息）列出儀表板的已儲存版本
取得儀表板摘要： 取得儀表板的精簡概覽，包括標題、面板數量、面板類型、變數和中繼資料，而不包含完整 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 參數明確設定。

SQL 資料來源查詢

注意： SQL 工具預設為停用。若要啟用，請將 sql 新增至您的 --enabled-tools 旗標。向後相容的別名 clickhouse、snowflake 和 athena 也可運作。

統一的 SQL 工具透過一組工具支援 ClickHouse、Snowflake、Athena、MySQL、PostgreSQL 和 MSSQL。查詢會透過 Grafana 的資料來源外掛程式進行，因此驗證由資料來源設定處理——MCP 伺服器永遠不會看到憑證。

列出資料庫/結構描述/目錄： 探索 SQL 資料來源的組織單位。對於 Athena，省略目錄以列出目錄，或傳入目錄以列出資料庫。
列出資料表： 列出資料庫或結構描述中的資料表，並附上中繼資料（列數、大小，如果有的話）。
描述資料表結構描述： 取得欄位名稱、類型、可空性、預設值和註解。
查詢 SQL： 使用資料來源特定的巨集替換（$__timeFilter(col)、$__from/$__to、$__interval、${varname}）、自動限制執行和範本變數支援來執行 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 指標密度。

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 管理員角色授予。
策劃已儲存的對話和集合： 讀取已儲存的對話（為對話提供穩定 ID、名稱和標籤的書籤）以及將它們分組的集合，包括每個集合的成員數量和每個已儲存對話列中嵌入的集合。啟用寫入工具後，也可為對話加入書籤、建立和編輯集合，以及新增或移除成員。這些寫入操作需要相同的 grafana-agento11y-app.eval:write 權限。
讀取和編輯測試套件： 列出離線實驗所針對的版本化測試套件，讀取一個套件及其完整版本歷史，並分頁瀏覽版本的測試案例。啟用寫入工具後，也可建立套件、重新命名或重新標記、開啟草稿版本、發佈，以及寫入或刪除其測試案例。已發佈的版本是凍結的，因此編輯意味著開啟新的草稿。這些寫入操作需要 grafana-agento11y-app.eval:write。
讀取離線實驗： 列出針對測試套件的評估執行，並讀取一個執行及其主要通過率、成本和 token 總數。透過每個測試案例的報告向下鑽研至試驗、其每個評判的說明分數，以及其工件中繼資料。啟用寫入工具後，也可重新命名或重新標記實驗，以及取消執行中的實驗，這需要 grafana-agento11y-app.eval:write。實驗由 SDK 執行器建立，而非此工具。

Grafana Assistant

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

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

事件（Incidents）

搜尋、建立和更新事件： 在 Grafana Incident 中管理事件，包括搜尋、建立、新增活動，以及讀取或設定自訂欄位。

Sift 調查

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

警示（Alerting）

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

Grafana OnCall

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

管理（Admin）

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

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

使用者（User）

使用者資訊： 取得目前的 Grafana 身分——登入名稱、電子郵件、姓名、是否為 Grafana（伺服器）管理員、目前組織，以及該憑證可存取的組織（含角色）。使用它來探索有效的 orgId 值，以用於多組織請求。

導覽（Navigation）

產生深層連結： 為 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?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}）。低於 10.2 的 Grafana 無法理解 panes，因此對於這些版本，會改為輸出舊版的 ?left={...} 格式。
- 時間範圍支援： 在連結中新增時間範圍參數（from=now-1h&to=now）
- 自訂參數： 包含其他查詢參數，例如儀表板變數或重新整理間隔

註解（Annotations）

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

快照（Snapshots）

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

渲染（Rendering）

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

佈建（Provisioning）

列出佈建儲存庫： 列出為此 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:*`
`user_info`	使用者	目前的身分、能力與可存取的組織	無（已登入使用者）	—
`search_dashboards`	搜尋	依查詢、資料夾 UID、標籤或星號搜尋儀表板	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_dashboard_by_uid`	儀表板	依 uid 取得儀表板，可選擇已儲存的版本	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	儀表板	列出儀表板的已儲存版本（版本、作者、時間、訊息）	`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`	執行面板查詢*	執行一個或多個儀表板面板查詢	`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 中的事件，可選擇包含其自訂欄位值	檢視者角色	N/A
`create_incident`	事件	在 Grafana Incident 中建立事件，可選擇設定自訂欄位	編輯者角色	N/A
`add_activity_to_incident`	事件	在 Grafana Incident 中為事件新增活動項目	編輯者角色	N/A
`update_incident`	事件	更新 Grafana Incident 中的事件（狀態、嚴重性、標題或自訂欄位）	編輯者角色	N/A
`get_incident`	事件	依 ID 取得單一事件，包含其自訂欄位	檢視者角色	N/A
`list_incident_custom_fields`	事件	列出為事件設定的自訂欄位，包含其類型與選項	檢視者角色	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_sql_databases`	SQL*	列出 SQL 資料來源中的資料庫、結構描述或目錄	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	列出 SQL 資料來源中的資料表	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	取得資料表的欄位結構描述	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	使用巨集替換執行 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:*`
`list_cloudwatch_dimension_values`	CloudWatch*	列出維度鍵的值	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	執行 CloudWatch 指標查詢	`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`
`alerting_manage_rules`	Alerting	管理警示規則（列出、取得、版本、建立、更新、刪除）	`alert.rules:read` + `alert.rules:write` 用於變更	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	管理通知政策、聯絡點和時間間隔	`alert.notifications:read`	全域範圍
`alerting_manage_silences`	Alerting	管理警示靜音（列出、取得、建立、更新、到期）	`alert.instances:read` + `alert.instances:write` 用於變更	全域範圍
`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`	外掛特定範圍
`update_alert_group`	OnCall	確認、取消確認、解決或取消解決警示群組	`grafana-oncall-app.alert-groups:write`（和 `: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` 用於變更	不適用
`agento11y_manage_experiments`	Agent Observability*	讀取離線實驗、其試驗、分數、工件中繼資料和篩選面向；更新和取消實驗	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用於變更	不適用
`agento11y_manage_test_suites`	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:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	註釋	建立新的註釋（標準或 Graphite 格式）	`annotations:write`	`annotations:*`
`update_annotation`	註釋	更新註釋的特定欄位（部分更新）	`annotations:write`	`annotations:*`
`delete_annotation`	註釋	依 ID 刪除註釋	`annotations:delete`	`annotations:*`
`get_annotation_tags`	註釋	列出註釋標籤，可搭配選用篩選條件	`annotations:read`	`annotations:*`
`list_snapshots`	快照	列出儀表板快照，可搭配選用查詢與數量限制篩選	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_snapshot`	快照	依快照金鑰取得快照中繼資料與儀表板負載	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`create_snapshot`	快照	從完整的儀表板負載建立儀表板快照	`dashboards:write`	`dashboards:*` 或 `dashboards:uid:abc123`
`delete_snapshot`	快照	依快照金鑰刪除儀表板快照	`dashboards:write`	`dashboards:*` 或 `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
`search_docs`	文件	搜尋 Grafana 文件或列出產品群組（省略查詢以列出產品）	無（公開的 grafana.com/docs）	N/A
`get_doc`	文件	取得文件頁面；設定 outline_only 以取得標題，或設定 section 以進行範圍限制的擷取	無（公開的 grafana.com/docs）	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 伺服器的基礎路徑。/healthz 和 /metrics 一律在伺服器根目錄提供服務，不會置於此前綴之下 — 它們是僅供探測器和抓取器使用的內部端點，將它們與應用程式前綴分開，可讓您更輕鬆地透過反向代理公開 API，同時不會一併暴露這些端點
--endpoint-path：streamable-http 伺服器的端點路徑，附加於 --base-path 之後 — 預設值：/mcp
--server-name：用於 MCP 交握和 OTel service.name 的伺服器名稱 — 預設值：mcp-grafana。覆寫 GRAFANA_MCP_SERVER_NAME 環境變數
--instructions-append：附加至初始化時傳回給 MCP 用戶端的伺服器指示文字，讓每個連線的代理程式都能看到

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

Host/Origin 驗證會在 MCP 監聽器的每個路由上強制執行 — 包括 /sse、/mcp，以及共用該監聽器時的 /healthz / /metrics — 因此 DNS 重新綁定的瀏覽器無法觸及任何一個。Stdio 傳輸不受影響。--healthz-address 和 --metrics-address 會啟動一個未包覆的獨立監聽器。

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

呼叫端驗證（僅限 SSE / streamable-http）：

可選擇要求 MCP 用戶端向伺服器進行驗證。這與伺服器用來連線 Grafana 的憑證是分開的。Stdio 不受影響。

--server-auth-token：呼叫端必須以 Authorization: Bearer <token> 傳送的 Bearer 權杖。回退至 MCP_GRAFANA_SERVER_TOKEN 環境變數。設定後，沒有有效權杖的要求會在執行任何工具前以 401 拒絕。建議優先使用環境變數，以免密碼出現在處理程序引數中。

呼叫端驗證僅在設定 --server-auth-token 時強制執行。當未設定且伺服器綁定非迴路位址時，伺服器會啟動但記錄安全性錯誤 — 以 error 日誌層級發出，因此不會被 --log-level 隱藏（迴路和 stdio 不受影響）；未來的主要版本會將其改為啟動錯誤。在非迴路位址上啟用呼叫端驗證時，請使用 TLS（或 TLS 終止）。啟用呼叫端驗證時，已驗證的 Authorization 標頭會在要求到達 Grafana 前被剝離；在啟動時結合 --server-auth-token 與 GRAFANA_FORWARD_HEADERS=Authorization 會被拒絕。

除錯與日誌：

--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）。若為空，指標會在主伺服器上提供服務
--healthz-address：/healthz 的獨立位址（例如 :8080）。若為空，/healthz 會在主伺服器上提供服務。當兩個位址相符時，會與 --metrics-address 共用監聽器。側邊監聽器會跳過 Host/Origin 驗證。
--slow-request-threshold：當任何 MCP 要求（工具呼叫、清單、資源讀取等）耗時超過此持續時間時記錄事件。接受 Go 持續時間字串（例如 500ms、5s）。預設 0 會停用慢速要求日誌。請參閱慢速要求日誌一節。
--slow-request-log-level：慢速要求事件的日誌層級（info 或 warn）— 預設值：warn。

匿名使用統計：

--usage-stats：匿名使用統計回報：enabled、disabled 或 log（列印原本會傳送至 stderr 的回報且不傳送任何內容）。覆寫 GRAFANA_USAGE_STATS 環境變數，而該變數又覆寫 DO_NOT_TRACK；任何無法辨識的值都會停用回報。請參閱匿名使用統計一節。

工作階段管理：

--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 以偵測是否還有更多資料）。
--loki-guardrail-mode：query_loki_logs 的 Loki 查詢成本防護 — 預設值：off。Loki 不會對沒有行篩選器的日誌查詢強制執行 max_query_bytes_read，因此對廣泛範圍的寬鬆選擇器可能掃描數 TB 的資料；防護機制要求具選擇性的串流選擇器、限制有效時間範圍（包括 range-vector 持續時間，如 [30d]），並在執行查詢前預先檢查 Loki 的索引/統計位元組估計。shadow 會記錄會被封鎖的查詢但允許其執行（仍會付出索引/統計往返成本）；enforce 會以 LLM 可據以行動的重寫指引拒絕這些查詢。在 VictoriaLogs 上，防護機制僅適用於選擇器形狀（{...}）的查詢 — 當沒有選擇器可解析（一般無大括號的 LogsQL 形狀）時，查詢會完全通過，且位元組預算檢查永遠不適用（沒有廉價的索引估計）。環境變數回退：GRAFANA_LOKI_GUARDRAIL_MODE。
--loki-guardrail-max-bytes：單次 query_loki_logs 呼叫可掃描的最大位元組數，透過 Loki 的索引/統計 API 估計 — 預設值：107374182400（100 GiB）。0 會停用位元組預算檢查。環境變數回退：GRAFANA_LOKI_GUARDRAIL_MAX_BYTES。
--loki-guardrail-max-range：單次 query_loki_logs 呼叫的最大有效時間範圍，包括 range-vector 持續時間 — 預設值：24h。接受 Go 持續時間字串。0 會停用範圍檢查。環境變數回退：GRAFANA_LOKI_GUARDRAIL_MAX_RANGE。
--loki-enforced-matchers：以 AND 併入每個原生 Loki 查詢的 LogQL 標籤比對器，以限制可讀取的日誌串流（例如 environment=~"prod|staging"）。需要 --disable-api。請參閱 Loki 查詢強制執行。
--loki-label-enumeration-fallback：當負向強制比對器無法限定標籤列舉工具時的行為：reject（預設）或 unfiltered。請參閱 Loki 查詢強制執行。
--disable-search：停用搜尋工具
--disable-datasource：停用資料來源工具
--disable-incident：停用事件（incident）工具
--disable-prometheus：停用 Prometheus 工具
--disable-write：停用寫入工具（建立/更新操作）
--disable-query：停用查詢工具（對資料來源執行查詢的工具）；中繼資料和探索工具仍可使用
--enable-query：即使在 --disable-write 下仍保留原始 SQL 查詢工具（query_sql、query_influxdb）的註冊。等同於 --enable-write-tools=query_sql,query_influxdb；作為該常見情況的簡寫保留。
--enable-write-tools：即使在 --disable-write 下仍保留註冊的個別工具名稱清單（以逗號分隔），適用於寫入行為範圍足夠獨立重新啟用的工具（例如 find_error_pattern_logs,find_slow_requests）。對整個類別已停用的工具沒有影響，例如透過 --disable-sift。
--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-sql：停用 SQL 資料來源工具（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL）。別名 --disable-clickhouse、--disable-snowflake、--disable-athena 也可使用。
--disable-runpanelquery：停用執行面板查詢工具
--disable-graphite：停用 Graphite 工具
--disable-provisioning：停用佈建工具
--disable-agento11y：停用 Agent Observability 工具
--disable-assistant：停用 Grafana Assistant 工具
--disable-docs：停用文件工具

唯讀模式

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

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

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

儀表板工具：

update_dashboard

資料夾工具：

create_folder

事件（Incident）工具：

create_incident
add_activity_to_incident
update_incident

警示工具：

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

OnCall 工具：

update_alert_group

註釋工具：

create_annotation
update_annotation
delete_annotation Sift 工具：
find_error_pattern_logs（建立調查）
find_slow_requests（建立調查）

這些工具僅透過 Sift API 建立暫時性的 Sift 調查記錄——它們絕不會觸及 Grafana 儀表板、警示或資料來源。沒有它們，list_sift_investigations/get_sift_investigation/get_sift_analysis 就沒有東西可以列出或取得。傳遞 --enable-write-tools=find_error_pattern_logs,find_slow_requests 以將它們保留在 --disable-write 下註冊。

快照工具：

create_snapshot
delete_snapshot

原始 SQL 查詢工具：

這些工具會執行您提供的任何查詢，而不會檢查其內容，因此當資料來源憑證允許時，它們可以執行寫入操作——query_sql 會執行 DROP TABLE，query_influxdb 會執行 DELETE。因此，唯讀模式會移除它們。當已知資料來源憑證為唯讀時，請傳遞 --enable-query 以保留它們。

query_sql
query_influxdb

代理可觀測性工具：

agento11y_manage_evaluators（upsert、刪除、分叉、測試評估器操作）
agento11y_manage_eval_rules（建立、更新、刪除、預覽規則和防護操作）
agento11y_manage_eval_collections（儲存和刪除已儲存的對話；建立、更新、刪除集合；新增和移除集合成員）
agento11y_manage_experiments（更新和取消實驗操作）
agento11y_manage_test_suites（建立和更新測試套件；建立和發布版本；upsert 和刪除測試案例）

所有讀取操作仍然可用，讓您可以查詢儀表板、執行 PromQL/LogQL 查詢、列出資源以及擷取資料。無法表達寫入操作的查詢語言——PromQL、LogQL、TraceQL、Elasticsearch DSL、Graphite、CloudWatch——在唯讀模式下會保留其查詢工具；只有上面列出的原始 SQL 工具會被移除。

無查詢模式

--disable-query 旗標會移除所有對資料來源執行查詢的工具，同時保留中繼資料和探索工具。當您希望助理能夠探索現有內容——資料來源、儀表板、指標名稱、標籤、資料表結構——而不執行潛在成本高昂或會揭露資料的查詢時，這非常有用，例如當服務帳戶具有 datasources:read 但沒有 datasources:query 時。

這是三種查詢設定中最嚴格的一種，並且優先於 --enable-query：

旗標	安全查詢工具（`query_prometheus`、`query_loki_logs`、`run_panel_query`、…）	原始 SQL 查詢工具（`query_sql`、`query_influxdb`）
（無）	已註冊	已註冊
`--disable-write`	已註冊	未註冊
`--disable-write --enable-query`	已註冊	已註冊
`--disable-query`	未註冊	未註冊
`--disable-query --enable-query`	未註冊	未註冊

當啟用 --disable-query 時，以下工具不會被註冊：

Prometheus 工具：

query_prometheus
query_prometheus_histogram

Loki 工具：

query_loki_logs
query_loki_patterns

query_loki_stats 和 analyze_loki_labels 保持註冊狀態：兩者都會向資料來源發送選擇器，但它們讀取索引並回傳串流、區塊和位元組計數，而不是日誌內容。

Elasticsearch/OpenSearch 和 Quickwit 工具：

query_elasticsearch
query_quickwit

InfluxDB 工具（也會被 --disable-write 移除，見上文）：

query_influxdb

SQL 資料來源工具（也會被 --disable-write 移除，見上文）：

query_sql

Graphite 工具：

query_graphite
query_graphite_density

CloudWatch 工具：

query_cloudwatch

Pyroscope 工具：

query_pyroscope

執行面板查詢工具：

run_panel_query

elasticsearch、quickwit、influxdb 和 runpanelquery 類別中沒有其他內容，因此在停用查詢時，它們不會註冊任何工具。其他每個類別中的同級工具——list_prometheus_metric_names、list_loki_label_values、describe_sql_table、list_cloudwatch_metrics 等等——仍然可用。

請注意，--disable-query 會控管查詢工具和 grafana_api_request POST 到 /api/ds/query 的路徑，但不會監管通往資料來源的每一條路由。在唯讀模式下，grafana_api_request 僅在查詢工具啟用時允許 POST 到 /api/ds/query（與原始 SQL 工具相同的控管——除非 --enable-query 覆寫，否則會被 --disable-write 封鎖）。get_panel_image 在伺服器端渲染面板，不受影響。

用戶端 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 標頭，確保操作在指定的組織內容中執行。

動態（每次呼叫）組織選擇

上述選項會為整個連線固定組織。若要讓單一連線在每次工具呼叫時針對不同組織，請使用 --dynamic-multi-org 旗標啟動伺服器。此功能預設為關閉。

啟用後，每個工具都會接受一個選用的 orgId 引數，該引數會覆寫該次呼叫的連線組織（同時驅動 X-Grafana-Org-Id 標頭，以及對於應用程式平台 API，解析後的 Kubernetes 命名空間）。代理的資料來源工具也會在憑證可存取的每個組織中額外被探索。省略 orgId 的呼叫會使用連線的預設組織。

這僅適用於屬於多個組織的憑證（例如使用者或代表身分）；服務帳戶權杖仍綁定於其單一組織。使用 user_info 工具來探索哪些 orgId 值是有效的。

具有組織 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\"}"
      }
    }
  }
}

SOCKS5 代理

您可以使用 GRAFANA_SOCKS5_PROXY 環境變數，將此伺服器對 Grafana 發出的所有請求路由透過 SOCKS5 代理。該代理僅限於此伺服器的 Grafana 流量：它不會修改全域 HTTP_PROXY/HTTPS_PROXY 變數，而且設定後，它僅會覆寫 Grafana 傳輸的代理選擇，不會影響其他 MCP 伺服器或您的 shell 工作階段。未設定時，行為保持不變。

URL 必須使用 socks5:// 或 socks5h:// 配置（Go 將它們視為相同：主機名稱解析委派給代理），並且可能包含憑證，例如 socks5://user:pass@127.0.0.1:1080。

範例：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

無效的代理 URL 會導致啟動錯誤，如果建立代理連線在執行時期失敗，伺服器會以失敗關閉，而不是靜默地直接發送 Grafana 流量。

從用戶端轉發標頭（僅限 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 中定義的任何標頭合併。如果標頭名稱同時出現在兩者中，則該請求的傳入請求值優先。

追蹤內容標頭（traceparent、tracestate、baggage）是例外：伺服器會自行傳播追蹤內容，因此轉發的值永遠不會覆寫其注入的值。請參閱可觀測性。

您有幾個選項可以安裝 mcp-grafana：
- uvx（建議）：如果您已安裝 uv，則無需額外設定——uvx 會自動下載並執行伺服器：
```
uvx mcp-grafana
```
- Docker 映像：使用 Docker Hub 的預建 Docker 映像。
  
  重要：Docker 映像的進入點預設設定為以 SSE 模式執行 MCP 伺服器，但大多數使用者會想要使用 STDIO 模式以直接與 Claude Desktop 等 AI 助理整合：
  1. 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 和 streamable-http 模式中，容器會綁定非迴環位址（0.0.0.0:8000）。沒有呼叫者權杖時，伺服器會啟動但記錄安全性錯誤（在 error 日誌層級，因此不會被 --log-level 隱藏；而且在未來的主要版本中將拒絕啟動）。設定 MCP_GRAFANA_SERVER_TOKEN 以要求用戶端提供 Authorization: Bearer <token>（建議）。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> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth 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> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

若為使用伺服器 TLS 憑證的 HTTPS streamable HTTP 模式：

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> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth 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 模式。

使用 VSCode 搭配遠端 MCP 伺服器

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

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

若為使用伺服器 TLS 憑證的 HTTPS streamable HTTP 模式：

"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 資料來源用戶端
事件管理用戶端
Sift 調查用戶端
警示用戶端
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 的內容函式：

// 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)

URL 驗證：

直接呼叫 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)

伺服器 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

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

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

匿名使用統計

伺服器可以向 Grafana Labs 回報關於自身的匿名使用統計：呼叫了哪些工具、其中有多少呼叫失敗，以及伺服器的設定方式。一份報告涵蓋一個伺服器程序——而非一個使用者或一個對話——並且每 4 小時發送一次，加上關閉時發送一次。此版本預設停用回報——接收端點尚未上線——後續版本將變更預設為啟用，並提供相同的退出選項。

工具引數、資源名稱、查詢、記錄行、錯誤訊息和憑證絕不會被發送。旗標僅依名稱記錄，絕不記錄值，且 Grafana 執行個體僅描述為 cloud 或 self_hosted——絕不透過 URL、主機名稱、堆疊 slug 或組織識別。沒有任何內容是依使用者、依工作階段或依用戶端區分的：線上沒有工作階段識別碼，也無法將工具呼叫歸因於特定用戶端。

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 也會停用回報，遵循跨工具的 DO_NOT_TRACK 慣例。只有 1 有效果，它只能停用，且 --usage-stats 和 GRAFANA_USAGE_STATS 都會覆寫它，因此全域設定它的主機仍可讓單一伺服器選擇重新啟用。

GRAFANA_USAGE_STATS_ENDPOINT 會變更目的地。它不是退出選項。

如需完整的欄位清單、絕不會發送的內容、如何讀取資料及其限制，請參閱匿名使用統計。

可觀測性

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 傳輸無法使用。

當啟用 Loki 成本防護機制（--loki-guardrail-mode）時，會新增四個計數器來記錄其決策：

指標	類型	說明
`mcp_loki_guardrail_admitted_total`	Counter	通過所有已啟用檢查的查詢（標籤：`backend`）
`mcp_loki_guardrail_would_block_total`	Counter	在 `shadow` 模式中未通過檢查但仍執行的查詢（標籤：`backend`、`reason`）
`mcp_loki_guardrail_blocked_total`	Counter	在 `enforce` 模式中被拒絕的查詢（標籤：`backend`、`reason`）
`mcp_loki_guardrail_fail_open_total`	Counter	防護機制無法評估且已允許的查詢（標籤：`backend`、`cause`）

reason 是 selector、range、bytes 之一；cause 是 unparseable、estimate_failed 之一；backend 是 loki、victorialogs、unknown 之一。觸發多項檢查的查詢只會被計數一次，並標記為最先執行的檢查（selector，接著是 range，然後是 bytes），因此四個計數器會劃分受防護的群體。請參閱可觀測性以了解如何在 shadow → enforce 推出期間讀取它們。

程式庫嵌入者應設定 GrafanaConfig.MeterProvider（GrafanaConfig.Logger 的指標對應項）：防護機制在工具處理常式內執行，因此沒有建構函式選項，而安裝 noop 全域 MeterProvider 的程序否則會丟棄每個記錄。

慢速請求記錄

--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 追蹤內容傳播。

日誌

當設定 OTEL_EXPORTER_OTLP_ENDPOINT（或訊號專屬的 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT）時，伺服器除了既有的純文字 stderr 輸出外，也會透過 OTLP/gRPC 匯出結構化日誌。otelslog 橋接器會自動從作用中的 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

Loki 查詢強制執行

--loki-enforced-matchers 讓操作員可以限制伺服器能讀取的 Loki 日誌串流，方法是將一組固定的 LogQL 標籤比對器以 AND 方式合併到伺服器發出的每個原生 Loki 查詢中。當資料來源包含不得公開的串流（例如可能攜帶敏感資訊的日誌），但您無法在 Grafana 或 Loki 層限制存取時（OSS 沒有依資料來源或依使用者的標籤存取控制），這會很有用。

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

運作方式：

比對器會在啟動時解析一次（無效輸入會中止伺服器），並附加到每個查詢中的每個串流選擇器。由於 Loki 會在選擇器內以 AND 方式合併比對器，使用者查詢只能在強制範圍內縮小結果——永遠無法擴大。與政策衝突的使用者選擇器（例如在排除條件下要求 {namespace="vault"}）只會回傳空結果。
涵蓋 query_loki_logs、query_loki_stats、query_loki_patterns、list_loki_label_names 和 list_loki_label_values。
它預設拒絕：任何無法解析的查詢都會被拒絕，而不是未經篩選就送出。
VictoriaLogs 資料來源使用 LogsQL，無法安全地改寫，因此在啟用強制執行時會完全拒絕。
純負向比對器無法限定標籤列舉端點（Loki 會拒絕沒有正向比對器的獨立選擇器）。請使用 --loki-label-enumeration-fallback 控制這個邊緣情況（預設為 reject，或使用 unfiltered 允許未限定的標籤中繼資料列舉——日誌行永遠不會被公開）。正向/允許清單比對器不受影響。

[!IMPORTANT] 強制執行僅適用於 Loki 查詢工具。其他工具可以透過不會觸及受強制後端的方式存取 Loki 日誌資料，因此要讓限制實際生效，您也必須停用它們：

--disable-api — grafana_api_request 可以直接查詢 Loki 資料來源代理（完全繞過）。

--disable-rendering — get_panel_image 會在伺服器端渲染 Loki 面板，產生包含未受限日誌行的影像。

--disable-sift — Sift 調查會在伺服器端分析所有串流的 Loki 日誌。

--disable-assistant — ask_assistant 會委派給 Grafana Assistant，它會在伺服器端讀取所有串流的 Loki。僅在啟用寫入工具時註冊，因此 --disable-write 也會關閉它。

伺服器會在啟動時記錄警告，列出仍啟用的每個項目。 run_panel_query 是安全的（它重複使用受強制的查詢路徑）。Tempo 工具查詢的是追蹤，而非 Loki 日誌，因此它們不是繞過途徑。儀表板快照（--disable-snapshot）也可能嵌入在強制執行之外擷取的日誌面板資料。

疑難排解

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 或更新版本以解決此問題。

開發

歡迎貢獻！請先閱讀 CONTRIBUTING.md——其中涵蓋了此伺服器應包含的內容以及如何提出建議。

如果您要新增工具，請在撰寫程式碼前先開啟工具提案。每個預設開啟的工具都會在每次請求時傳送給每個使用者的模型，因此我們寧可先討論想法，也不願拒絕已完成的功能請求。錯誤修正、文件、測試和現有工具的新參數不需要提案——直接送出 PR 即可。

此專案使用 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

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

Lint

若要對程式碼執行 lint，請執行：

make lint

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

make lint-jsonschema

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

授權

此專案採用 Apache License, Version 2.0 授權。