Grafana

官方

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

GitHub

3.7k

你可以用 Grafana MCP 做什麼？

搜尋和檢視儀表板 — 依標題、資料夾、標籤或星號狀態尋找儀表板，然後透過 JSONPath 擷取精簡摘要或特定屬性。
無需完整 JSON 即可修補儀表板 — 對現有儀表板套用目標變更，或使用完整 JSON 建立及更新儀表板。
查詢 Prometheus 和 Loki — 執行 PromQL 指標查詢和 LogQL 日誌或指標查詢，並擷取指標中繼資料、標籤和日誌模式。
查詢 SQL 資料來源 — 列出資料庫、資料表和結構描述，描述資料表欄位，並對 ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL 或 BigQuery 執行 SQL。
管理警示和事件 — 列出、建立、更新及刪除警示規則，檢視通知政策和聯絡點，並搜尋或更新 Grafana Incident 記錄。
產生深層連結並轉譯面板 — 建立準確的儀表板、面板和 Explore URL，並將面板或儀表板轉譯為 PNG 圖片。

文件

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）。如需其他安裝方式，包括 Docker、二進位檔和 Helm，請參閱使用方式。

需求

完整功能需要 Grafana 9.0 或更新版本。由於缺少 API 端點，部分功能（尤其是與資料來源相關的操作）在較舊版本中可能無法正常運作。

功能

以下列出 MCP 伺服器目前提供的功能。此清單僅供參考，不代表未來功能的規劃或承諾。

儀表板

搜尋儀表板： 依標題、資料夾 UID、標籤或星號狀態尋找儀表板
依 UID 取得儀表板： 使用唯一識別碼擷取完整的儀表板詳細資料。傳入選用的 version，即可載入已儲存的快照，而非目前的儀表板。警告：大型儀表板可能會佔用大量上下文視窗空間。
列出儀表板版本： 以精簡的中繼資料（版本號碼、作者、時間戳記、儲存訊息）列出儀表板的已儲存版本
取得儀表板摘要： 取得儀表板的精簡概覽，包括標題、面板數量、面板類型、變數和中繼資料，不含完整 JSON，以減少上下文視窗用量
取得儀表板屬性： 使用 JSONPath 運算式（例如 $.title、$.panels[*].title）擷取儀表板的特定部分，只取得所需資料並減少上下文視窗用量
更新或建立儀表板： 修改現有儀表板或建立新儀表板。警告：需要完整的儀表板 JSON，可能會佔用大量上下文視窗空間。
修補儀表板： 對儀表板套用特定變更，無須提供完整 JSON，大幅減少針對性修改的上下文視窗用量
取得面板查詢和資料來源資訊： 取得儀表板中每個面板的標題、查詢字串和資料來源資訊（包括 UID 和類型，如有提供）

執行面板查詢

注意： 面板查詢工具預設為停用。若要啟用，請將 runpanelquery 加入您的 --enabled-tools 旗標。

執行面板查詢： 使用自訂時間範圍和變數覆寫來執行儀表板面板的查詢。Infinity 面板會在查詢使用 backend 或 jq-backend 剖析器時執行（Google Sheets 查詢一律使用其中之一）；預設的 simple 剖析器以及 UQL 和 GROQ 剖析器僅能在瀏覽器中運作。使用 kniepdennis-neo4j-datasource 外掛程式的 Neo4j 面板會透過外掛程式執行 Cypher 查詢，並開啟唯讀工作階段。

上下文視窗管理

儀表板工具現在提供多種策略，可有效管理上下文視窗用量（問題 #101）：

使用 get_dashboard_summary 概覽儀表板並規劃修改
僅需儀表板特定部分時，使用搭配 JSONPath 的 get_dashboard_property
除非確實需要完整的儀表板 JSON，否則避免使用 get_dashboard_by_uid

資料來源

列出並擷取資料來源資訊： 檢視所有已設定的資料來源，並擷取各資料來源的詳細資訊。
- 支援的資料來源類型：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch、OpenSearch、Snowflake、Athena。
資料來源資源： 您可存取的每個資料來源也會以 MCP 資源形式公開於 grafana://datasources/{uid}，因此您可以直接將其附加至對話（例如在 Claude Code 中使用 @），而不必讓模型自行查找。停用資料來源工具時，此功能也會一併停用。

查詢範例

注意： 查詢範例工具預設為停用。若要啟用，請將 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 和 BigQuery。查詢會透過 Grafana 的資料來源外掛程式執行，因此驗證由資料來源設定處理，MCP 伺服器不會取得憑證。

列出資料庫／結構描述／目錄： 探索 SQL 資料來源的組織單位。對 Athena 而言，省略目錄即可列出目錄，或傳入目錄以列出資料庫。
列出資料表： 列出資料庫或結構描述中的資料表及其中繼資料（可用時包括資料列數和大小）。
描述資料表結構描述： 取得欄名稱、類型、是否可為 null、預設值和註解。
查詢 SQL： 執行 SQL 查詢，支援資料來源專屬的巨集替換（$__timeFilter(col)、$__from/$__to、$__interval、${varname}）、自動限制結果數量，以及範本變數。

對於 BigQuery，請在 Grafana 中設定 grafana-bigquery-datasource 外掛程式。探索功能會使用 database 取得專案，並使用 schema 取得資料集。若省略 database，專案會依序預設為資料來源的 defaultProject，再來是外掛程式的 /defaultProjects 端點（包括 GCE 專案探索）。中繼資料僅透過 API 擷取，不會執行查詢工作或掃描資料表。結果包含欄描述和巢狀類型；外掛程式不提供資料表描述／類型、欄位是否可為 null，以及預設值。

BigQuery 查詢需要使用限定資料表參照，例如 `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring}，以逸出字串變數。資料列限制不會限制掃描的位元組數或查詢成本。

CloudWatch 查詢

注意： CloudWatch 工具預設為停用。若要啟用，請將 cloudwatch 加入您的 --enabled-tools 旗標。

列出 CloudWatch 命名空間： 探索可用的 AWS CloudWatch 命名空間。
列出 CloudWatch 指標： 列出特定命名空間中可用的指標。
列出 CloudWatch 維度： 取得用於篩選指標查詢的維度。
查詢 CloudWatch： 執行支援時間範圍的 CloudWatch 指標查詢。
列出 CloudWatch 日誌群組： 探索日誌群組，可選擇依名稱前綴篩選。
列出 CloudWatch 日誌群組欄位： 探索日誌群組中可用的欄位。
查詢 CloudWatch Logs： 對一或多個日誌群組執行 CloudWatch Logs Insights 查詢。

Google Cloud Logging 查詢

注意： Google Cloud Logging 工具預設為停用。若要啟用，請將 cloudlogging 加入您的 --enabled-tools 旗標。需要 Google Cloud Logging 資料來源外掛程式（googlecloud-logging-datasource）1.8.0 或更新版本，且需要 Grafana 11.2 以上版本。較舊的外掛程式版本會傳回不同的回應版面配置，而 query_cloud_logging 會回報錯誤並要求升級。

列出 Cloud Logging 專案： 探索資料來源可讀取日誌的 GCP 專案 ID。
列出 Cloud Logging bucket 和檢視： 探索日誌 bucket 和日誌檢視，以限定查詢範圍。
查詢 Cloud Logging： 執行 Cloud Logging 查詢語言篩選條件（例如 resource.type="k8s_container" AND severity>=ERROR），並指定時間範圍和限制；結果會依時間由新到舊傳回項目，包含嚴重性、本文、標籤和追蹤 ID。GCP 驗證由資料來源設定處理。

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 對話，或在指定時間範圍內使用篩選運算式（模型、提供者、代理程式、狀態、錯誤類型、評估結果等）搜尋對話。搜尋結果包含錯誤數量、評分摘要、評估摘要及追蹤 ID。
取得對話詳細資料： 擷取單一對話及其所有生成內容，包括提示和輸出。
取得生成詳細資料及評分： 依 ID 擷取單一生成內容及其評估分數（評估器、分數鍵、值、是否通過、說明）。
讀取代理程式目錄： 列出會傳送遙測資料的代理程式，完整擷取某個代理程式版本（完整系統提示、每個工具及其 JSON 結構描述，以及該代理程式執行時使用的模型）、瀏覽代理程式的版本歷程記錄，並比較各版本的評估分數彙總。有效版本是 sha256: 雜湊，不會因工具變更而受影響；對於未回報自身版本的代理程式，雜湊會使用系統提示，因此編輯提示會產生新版本。目錄和版本資料列都帶有 token_estimate，擷取完整提示前值得先檢查。
檢查評估器和範本： 讀取分數所使用的評估器、評估器衍生自哪些範本，以及 LLM 評審評估器可用的評審提供者和模型。啟用寫入工具後，也可以建立、分支、測試及刪除評估器。
檢查評估規則和防護機制： 讀取將評估器套用至正式流量的非同步評估規則，以及內嵌執行並可發出警告或拒絕請求的防護機制（掛鉤規則）。啟用寫入工具後，也可以建立、更新、預覽及刪除這些項目。寫入操作，以及不會持久化資料的 preview_rule 和 test_evaluator 操作，都需要 grafana-agento11y-app.eval:write 權限；此權限由 Agento11y Admin 角色授予。
整理已儲存的對話和集合： 讀取已儲存的對話（書籤會為對話提供穩定 ID、名稱和標籤）及其所屬集合，包括每個集合的成員數，以及每個已儲存對話資料列中內嵌的集合。啟用寫入工具後，也可以將對話加入書籤、建立和編輯集合，以及新增或移除成員。這些寫入操作需要相同的 grafana-agento11y-app.eval:write 權限。
讀取及編輯測試套件： 列出離線實驗所使用的版本化測試套件，讀取套件及其完整版本歷程記錄，並分頁瀏覽某個版本的測試案例。啟用寫入工具後，也可以建立套件、重新命名或重新標記套件、開啟草稿版本、發布版本，以及新增或刪除測試案例。已發布的版本會凍結，因此編輯時必須開啟新的草稿。這些寫入操作需要 grafana-agento11y-app.eval:write。
讀取離線實驗： 列出針對測試套件執行的評估，並讀取單次評估的整體通過率、成本和權杖總數。深入查看每個測試案例的報告、試驗、各評審的說明及其分數，以及試驗的成品中繼資料。啟用寫入工具後，也可以重新命名或重新標記實驗，以及取消執行中的實驗；這些操作需要 grafana-agento11y-app.eval:write。實驗由 SDK 執行器建立，而非由此工具建立。

Grafana Assistant

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

詢問 Assistant： 向 Grafana Assistant 傳送自然語言提示，並等待完整文字回覆。Assistant 可能會使用工具、指標、日誌及其他堆疊脈絡，涵蓋範圍比單獨執行一個資料來源查詢更廣。在後續呼叫中傳入傳回的 contextId，即可繼續相同的對話。複雜工作可能需要數分鐘；呼叫會持續等待，直到回覆完成或請求逾時（5 分鐘）。

事件

搜尋、建立及更新事件： 管理 Grafana Incident 中的事件，包括搜尋、建立、新增活動，以及讀取或設定自訂欄位。
事件資源： 過去 30 天內開始的作用中事件也會以 MCP 資源形式公開於 grafana://irm/incidents/{id}，因此你可以直接將事件附加至對話（例如在 Claude Code 中使用 @）。停用事件工具時，這些資源也會一併停用。

警示

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

Grafana OnCall

列出及管理排班表： 檢視及管理 Grafana OnCall 中的待命排班表。
取得輪班詳細資料： 擷取特定待命輪班的詳細資訊。
取得目前待命使用者： 查看目前負責某個排班表的使用者。
列出團隊和使用者： 檢視所有 OnCall 團隊和使用者。
列出警示群組： 依狀態、整合、標籤和時間範圍等條件，檢視及篩選 Grafana OnCall 的警示群組。
取得警示群組詳細資料： 依 ID 擷取特定警示群組的詳細資訊。

管理

注意： 管理工具預設為停用。若要啟用，請將 admin 加入 --enabled-tools 旗標。

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

使用者

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

導覽

產生深層連結： 為 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）
- 自訂參數： 加入其他查詢參數，例如儀表板變數或重新整理間隔

註解

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

快照

列出快照： 列出儀表板快照，並可選擇使用查詢和數量上限篩選。
取得快照： 依快照金鑰擷取快照中繼資料和儀表板承載資料。
建立快照： 根據完整的儀表板承載資料建立儀表板快照，並可選擇設定到期時間和外部快照選項。
刪除快照： 依快照金鑰刪除快照。

渲染

取得面板或儀表板影像： 將 Grafana 儀表板面板或完整儀表板渲染為 PNG 影像。傳回 base64 編碼的影像資料，可用於報告、警示或簡報。面板預設為 1000×750 CSS 像素，完整儀表板預設為 1200×900，兩者的縮放比例皆為 1。Explore 預設為 1000×1000，縮放比例為 1。尺寸受影像渲染器的檢視區限制。支援自訂尺寸、時間範圍、佈景主題、縮放比例和儀表板變數。也支援透過選用的 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 伺服器操作；與手動套用範圍相比，它的細緻度較低（因此限制也較少），所以只有在便利性比嚴格遵循最低權限原則更重要時才使用。

注意： OnCall 和其他由外掛程式支援的工具，會透過外掛程式動作（例如 grafana-irm-app.schedules:read）進行授權。基本的 Viewer 角色包含讀取動作，Editor 則包含寫入動作。Incident 工具只需要 plugins.app:access；IRM 會依基本角色授權事件動作。

group/resource:verb 形式的動作（例如 dashboard.grafana.app/dashboards:get）僅適用於代表使用者存取的權杖。服務帳戶只需要其他列出的動作。

如需 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`	管理員*	列出組織中的使用者，並提供搜尋和分頁功能	`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`, `teams.roles:read`, `users.roles:read`	`roles:uid:editor`
`list_user_roles`	管理員*	列出使用者的角色	`users.roles:read`	`global.users:id:123`
`list_team_roles`	管理員*	列出團隊的角色	`teams.roles:read`	`teams:id:7`
`get_resource_permissions`	管理員*	列出資源的權限	`dashboards.permissions:read`, `datasources.permissions:read`, `folders.permissions:read`, `serviceaccounts.permissions:read`, `teams.permissions:read`, `users.permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	管理員*	描述 Grafana 資源類型	`dashboards.permissions:read`, `datasources.permissions:read`, `folders.permissions:read`, `serviceaccounts.permissions:read`, `teams.permissions:read`, `users.permissions:read`	`dashboards:*`
`user_info`	使用者	目前的身分、功能和可存取的組織	無	—
`search_dashboards`	搜尋	依查詢、資料夾 UID、資料夾路徑、標籤或星號標記搜尋儀表板	`dashboards:read`, `folders:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`search_folders`	搜尋	依標題搜尋資料夾	`folders:read`	`folders:*` 或 `folders:uid:xyz789`
`get_dashboard_by_uid`	儀表板	依 uid 取得儀表板，也可選擇取得已儲存的版本	`dashboard.grafana.app/dashboards:get`, `dashboards:read`, `dashboards:write`	`dashboards:uid:abc123`
`list_dashboard_versions`	儀表板	列出儀表板的已儲存版本（版本、作者、時間、訊息）	`dashboards:read`, `dashboards:write`	`dashboards:uid:abc123`
`update_dashboard`	儀表板	更新或建立新的儀表板	`dashboard.grafana.app/dashboards:create`, `dashboard.grafana.app/dashboards:get`, `dashboard.grafana.app/dashboards:update`, `dashboards:create`, `dashboards:read`, `dashboards:write`, `folders:read`	`dashboards:`, `folders:` 或 `folders:uid:xyz789`
`get_dashboard_panel_queries`	儀表板	從儀表板取得面板標題、查詢、資料來源 UID 和類型	`dashboard.grafana.app/dashboards:get`, `dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	執行一或多個儀表板面板查詢	`dashboard.grafana.app/dashboards:get`, `dashboards:read`, `datasources:query`, `datasources:read`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	儀表板	使用 JSONPath 運算式擷取儀表板的特定部分	`dashboard.grafana.app/dashboards:get`, `dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	儀表板	取得儀表板的精簡摘要，不含完整 JSON	`dashboard.grafana.app/dashboards:get`, `dashboards:read`	`dashboards:uid:abc123`
`create_folder`	Dashboard	建立資料夾	`folders:create`, `folders:read`, `folders:write`	`folders:*`
`list_datasources`	Datasources	列出資料來源	`datasources:read`	`datasources:*`
`get_datasource`	Datasources	依 UID 或名稱取得資料來源	`datasources:read`	`datasources:uid:prometheus-uid`
`check_datasources_health`	Datasources	檢查一或多個資料來源的健康狀態	`datasources:query`, `datasources:read`	`datasources:uid:*`
`create_datasource`	Datasources	建立資料來源	`datasources:create`, `datasources:read`	`datasources:*`
`update_datasource`	Datasources	更新資料來源	`datasources:read`, `datasources:write`	`datasources:*` 或 `datasources:uid:abc123`
`get_query_examples`	Examples*	取得資料來源類型的範例查詢	None	`datasources:*`
`query_prometheus`	Prometheus	使用 PromQL 查詢指標，無需開啟圖表	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`render_grafana_app`	Rendering	執行已啟用的查詢工具，並在互動式 Grafana App 中顯示結果	`datasources:query`, `datasources:read`	`datasources:*` 或 `datasources:uid:<uid>`
`list_prometheus_metric_metadata`	Prometheus	列出指標中繼資料	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	列出可用的指標名稱	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	列出符合選取器的標籤名稱	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	列出特定標籤的值	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	計算直方圖百分位數值	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	列出 Grafana Incident 中的事件，可選擇包含其自訂欄位值	`plugins.app:access`	N/A
`create_incident`	Incident	在 Grafana Incident 中建立事件，可選擇設定自訂欄位	`plugins.app:access`	N/A
`add_activity_to_incident`	Incident	在 Grafana Incident 中為事件新增活動項目	`plugins.app:access`	N/A
`update_incident`	Incident	更新 Grafana Incident 中的事件（狀態、嚴重性、標題或自訂欄位）	`plugins.app:access`	N/A
`get_incident`	Incident	依 ID 取得單一事件，包括其自訂欄位	`plugins.app:access`	N/A
`list_incident_custom_fields`	Incident	列出為事件設定的自訂欄位及其類型和選項	`plugins.app:access`	N/A
`query_loki_logs`	Loki	使用 LogQL 查詢並擷取日誌（日誌或指標查詢皆可）	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	列出日誌中所有可用的標籤名稱	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	列出特定日誌標籤的值	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	取得日誌串流的統計資料	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	查詢偵測到的日誌模式，以識別常見結構	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	稽核 Loki 標籤策略（即時或靜態），並可選擇診斷查詢效能	`datasources:query`, `datasources:read`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Config	產生強制使用核准標籤的 Alloy `loki.process` 片段	None	N/A
`query_influxdb`	InfluxDB*	使用 InfluxQL (v1) 或 Flux (v2) 查詢 InfluxDB	`datasources:query`, `datasources:read`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	列出 SQL 資料來源中的資料庫、結構描述或目錄	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_sql_tables`	SQL*	列出 SQL 資料來源中的資料表	`datasources:query`, `datasources:read`	`datasources:uid:*`
`describe_sql_table`	SQL*	取得資料表的欄位結構描述	`datasources:query`, `datasources:read`	`datasources:uid:*`
`query_sql`	SQL*	使用巨集替換執行 SQL 查詢	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	列出可用的 AWS CloudWatch 命名空間	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	列出命名空間中的指標	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	列出指標的維度	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	列出維度索引鍵的值	`datasources:query`, `datasources:read`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	執行 CloudWatch 指標查詢	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_log_groups`	CloudWatch*	列出 CloudWatch 日誌群組	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloudwatch_log_group_fields`	CloudWatch*	列出在日誌群組中探索到的欄位	`datasources:query`, `datasources:read`	`datasources:uid:*`
`query_cloudwatch_logs`	CloudWatch*	執行 CloudWatch Logs Insights 查詢	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	列出 Google Cloud Logging 資料來源可讀取的 GCP 專案	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	列出 GCP 專案中的日誌儲存桶	`datasources:query`, `datasources:read`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	列出記錄值區中的記錄檢視	`datasources:query`, `datasources:read`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	使用 Cloud Logging 查詢語言查詢記錄	`datasources:query`, `datasources:read`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	使用 Lucene 語法或 Query DSL 查詢 Elasticsearch 或 OpenSearch	`datasources:query`, `datasources:read`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	使用 Lucene 語法或 Query DSL 查詢 Quickwit	`datasources:query`, `datasources:read`	`datasources:uid:quickwit-uid`
`alerting_rules_read`	Alerting	列出並檢視警示規則（列出、取得、版本）	`alert.rules.external:read`, `alert.rules:read`, `datasources:read`, `folders:read`	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_rules_write`	Alerting	建立、更新及刪除 Grafana 管理的規則，或明確建立資料來源管理的規則	`alert.provisioning.provenance:write`, `alert.rules.external:read`, `alert.rules.external:write`, `alert.rules:create`, `alert.rules:delete`, `alert.rules:read`, `alert.rules:write`, `datasources:read`, `folders:read`	`folders:*`，或外部建立時使用 `datasources:uid:<uid>`
`alerting_manage_routing`	Alerting	管理通知政策、聯絡點和時間間隔	`alert.notifications.external:read`, `alert.notifications.receivers:read`, `alert.notifications.routes:read`, `alert.notifications.time-intervals:read`, `alert.notifications:read`, `datasources:query`, `datasources:read`, `notifications.alerting.grafana.app/routingtrees:get`	全域範圍
`alerting_routing_write`	Alerting	預設建立 Grafana 管理的聯絡點，或明確建立外部 Alertmanager 接收器	`alert.notifications.external:read`, `alert.notifications.external:write`, `alert.notifications.receivers:create`, `alert.provisioning.provenance:write`, `datasources:read`	全域，或外部建立時使用 `datasources:uid:<uid>`
`alerting_silences_read`	Alerting	列出並檢視警示靜默（列出、取得）	`alert.instances:read`, `alert.silences:read`	全域範圍
`alerting_silences_write`	Alerting	建立、更新及使警示靜默過期	`alert.instances:create`, `alert.instances:read`, `alert.instances:write`, `alert.silences:create`, `alert.silences:read`, `alert.silences:write`	全域範圍
`list_oncall_schedules`	OnCall	列出 Grafana OnCall 的排班表	`grafana-irm-app.schedules:read`, `plugins.app:access`	外掛程式專屬範圍
`get_oncall_shift`	OnCall	取得特定 OnCall 班次的詳細資料	`grafana-irm-app.schedules:read`, `plugins.app:access`	外掛程式專屬範圍
`get_current_oncall_users`	OnCall	取得目前負責特定排班表的值班使用者	`grafana-irm-app.schedules:read`, `grafana-irm-app.user-settings:read`, `plugins.app:access`	外掛程式專屬範圍
`list_oncall_teams`	OnCall	列出 Grafana OnCall 的團隊	`grafana-irm-app.user-settings:read`, `plugins.app:access`	外掛程式專屬範圍
`list_oncall_users`	OnCall	列出 Grafana OnCall 的使用者	`grafana-irm-app.user-settings:read`, `plugins.app:access`	外掛程式專屬範圍
`list_alert_groups`	OnCall	列出 Grafana OnCall 的警示群組，並提供篩選選項	`grafana-irm-app.alert-groups:read`, `plugins.app:access`	外掛程式專屬範圍
`get_alert_group`	OnCall	依 ID 取得 Grafana OnCall 中的特定警示群組	`grafana-irm-app.alert-groups:read`, `plugins.app:access`	外掛程式專屬範圍
`update_alert_group`	OnCall	確認、取消確認、解決或取消解決警示群組	`grafana-irm-app.alert-groups:read`, `grafana-irm-app.alert-groups:write`, `plugins.app:access`	外掛程式專屬範圍
`list_pyroscope_label_names`	Pyroscope	列出符合選取器的標籤名稱	`datasources:query`, `datasources:read`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	列出符合指定標籤名稱之選取器的標籤值	`datasources:query`, `datasources:read`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	列出可用的設定檔類型	`datasources:query`, `datasources:read`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	從 Pyroscope 查詢設定檔、指標或兩者	`datasources:query`, `datasources:read`	`datasources:uid:pyroscope-uid`
`agento11y_manage_conversations`	Agent Observability*	列出、搜尋及擷取 Grafana Agent Observability 中的 LLM 對話	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不適用
`agento11y_manage_generations`	Agent Observability*	從 Grafana Agent Observability 擷取 LLM 生成詳細資料和評估分數	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不適用
`agento11y_manage_agents`	Agent Observability*	讀取代理程式目錄：列出代理程式、完整取得單一代理程式版本、列出版本歷程記錄，以及各版本的分數彙總	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不適用
`agento11y_manage_evaluators`	Agent Observability*	管理評估器、評估器範本和裁判目錄（列出、取得、更新或插入、分支、測試、刪除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`; 啟用寫入時也包括 `grafana-agento11y-app.eval:write`	不適用
`agento11y_manage_eval_rules`	Agent Observability*	管理評估規則和防護措施（列出、取得、建立、更新、預覽、刪除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`; 啟用寫入時也包括 `grafana-agento11y-app.eval:write`	不適用
`agento11y_manage_eval_collections`	Agent Observability*	管理已儲存的對話及其所屬集合（列出、取得、儲存、建立、更新、刪除、新增及移除成員）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`; 啟用寫入時也包括 `grafana-agento11y-app.eval:write`	不適用
`agento11y_manage_experiments`	Agent Observability*	讀取離線實驗、其試驗、分數、成品中繼資料和篩選器面向；更新及取消實驗	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`; 啟用寫入時也包括 `grafana-agento11y-app.eval:write`	不適用
`agento11y_manage_test_suites`	Agent Observability*	管理離線實驗所使用的測試套件、其版本和測試案例（列出、取得、建立、更新、草稿、發布、更新或插入、刪除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`; 啟用寫入時也包括 `grafana-agento11y-app.eval:write`	不適用
`ask_assistant`	Assistant*	向 Grafana Assistant 傳送提示並傳回完整文字回覆（透過 `contextId` 進行多輪對話）	`grafana-assistant-app.chats:access`, `plugins.app:access`	外掛程式專屬範圍
`generate_deeplink`	導覽	為 Grafana 資源產生準確的深層連結 URL	無	不適用
`get_annotations`	註解	使用篩選條件擷取註解	`annotations:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	註解	建立新註解（標準或 Graphite 格式）	`annotations:create`	`annotations:*`
`update_annotation`	註解	更新註解的特定欄位（部分更新）	`annotations:read`, `annotations:write`	`annotations:*`
`delete_annotation`	註解	依 ID 刪除註解	`annotations:delete`	`annotations:*`
`get_annotation_tags`	註解	列出註解標籤，可選擇套用篩選條件	`annotations:read`	`annotations:*`
`list_snapshots`	快照	列出儀表板快照，可選擇使用查詢和限制條件篩選	`snapshots:read`	不適用
`get_snapshot`	快照	依快照金鑰取得快照中繼資料和儀表板承載資料	無	不適用
`create_snapshot`	快照	根據完整儀表板承載資料建立儀表板快照	`dashboards:read`, `snapshots:create`	`dashboards:uid:abc123`
`delete_snapshot`	快照	依快照金鑰刪除儀表板快照	`dashboards:write`, `snapshots:delete`	`dashboards:uid:abc123`
`get_panel_image`	繪製	將已儲存的儀表板或面板、佈建預覽或臨時 Explore 檢視繪製為 PNG 圖片	`dashboards:read`, `datasources:explore`, `datasources:query`, `datasources:read`, `provisioning.repositories:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	佈建	列出佈建儲存庫（例如 git-sync 來源），以及其來源 URL、分支、同步狀態和健康狀況	`provisioning.grafana.app/repositories:list`, `provisioning.repositories:read`	不適用
`validate_provisioning_file`	Provisioning	對佈建儲存庫中的檔案執行 dry-run-apply，並回報准入驗證錯誤	`dashboard.grafana.app/dashboards:get`, `dashboards:read`, `folder.grafana.app/folders:get`, `folders:read`, `provisioning.grafana.app/repositories:get`, `provisioning.repositories:read`	N/A
`search_docs`	Docs	搜尋 Grafana 文件或列出產品群組（省略查詢即可列出產品）	None	N/A
`get_doc`	Docs	擷取文件頁面；設定 outline_only 以取得標題，或設定 section 以限制擷取範圍	None	N/A
`search_tempo_traces`	Tempo	使用 TraceQL 搜尋追蹤資料	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`query_tempo_metrics`	Tempo	使用 TraceQL 計算追蹤資料的指標	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`get_tempo_trace`	Tempo	依 ID 擷取追蹤資料	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`diff_tempo_traces`	Tempo	比較兩筆追蹤資料	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`list_tempo_attribute_names`	Tempo	列出 span 和資源屬性名稱	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`list_tempo_attribute_values`	Tempo	列出追蹤屬性的值	`datasources:query`, `datasources:read`	`datasources:uid:tempo-uid`
`get_tempo_traceql_docs`	Tempo	取得 TraceQL 文件	None	N/A
`query_graphite`	Graphite*	查詢 Graphite 指標	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`query_graphite_density`	Graphite*	查詢 Graphite 指標密度	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`list_graphite_metrics`	Graphite*	列出 Graphite 指標	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`list_graphite_tags`	Graphite*	列出 Graphite 標籤	`datasources:query`, `datasources:read`	`datasources:uid:graphite-uid`
`get_plugin`	Plugins	取得已安裝的外掛程式	`plugins.app:access`	N/A
`search_plugin_information`	Plugins	搜尋 grafana.com 外掛程式目錄	None	N/A
`install_plugin`	Plugins	安裝外掛程式	`plugins:install`	N/A
`grafana_api_request`	API	呼叫 Grafana HTTP API 端點	None	依端點而定
* 預設為停用。將類別加入 `--enabled-tools` 以啟用。

當啟用渲染類別及對應的查詢類別時，render_grafana_app 工具會在相容的 MCP 主機中顯示指標和追蹤資料。來源查詢工具會傳回文字和結構化資料供分析使用。設定及嵌入程式庫的方式請參閱 MCP Apps。

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
--sse-keepalive：傳送至每個 SSE 用戶端的 ping 請求間隔，避免反向代理和負載平衡器關閉閒置的事件串流（這會結束工作階段）。請將此值設為低於代理的閒置逾時，例如在 ingress-nginx 預設的 60s proxy-read-timeout 後方使用 30s。若連續 3 次 ping 均未獲回應，且每次等待半個間隔，則會中斷用戶端連線。接受 Go duration 字串，最小值為 1s - 預設值：0（停用）。僅適用於 --transport sse
--server-name：MCP 握手和 OTel service.name 中使用的伺服器名稱 - 預設值：mcp-grafana。會覆寫 GRAFANA_MCP_SERVER_NAME 環境變數
--instructions-append：附加至初始化時傳回給 MCP 用戶端的伺服器指示文字，讓每個連線的代理都能看到

[!NOTE] 使用 SSE 時，每個請求的標頭不會傳遞至工具呼叫：X-Grafana-Service-Account-Token / X-Grafana-API-Key、X-Grafana-Org-Id 以及 GRAFANA_FORWARD_HEADERS 中列出的標頭都不會生效；工具呼叫會使用伺服器的環境憑證，且 X-Grafana-URL 覆寫也不會生效。若每個呼叫端都需要使用自己的 Grafana URL、憑證或組織，請使用 streamable-http。

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

Host/Origin 驗證會套用至 MCP 接聽程式上的每個路由 — 包括 /sse、/mcp，以及共用該接聽程式時的 /healthz / /metrics — 因此 DNS 重新繫結瀏覽器無法存取其中任何一個。Stdio 傳輸不受影響。--healthz-address 和 --metrics-address 會啟動不受此驗證包裝的獨立接聽程式。

--allowed-hosts：以逗號分隔的 Host 標頭值允許清單。預設為 --address 的迴路變體（例如 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 標頭的請求都會遭拒（瀏覽器在跨來源請求中一律會傳送此標頭，而且不應有任何瀏覽器直接呼叫此伺服器）。設定明確清單以允許瀏覽器用戶端，或設定為 * 以停用檢查。
--allow-grafana-url-override：啟用 X-Grafana-URL 選取。會回退至 GRAFANA_ALLOW_URL_OVERRIDE；預設為停用。若未設定允許清單，呼叫端可選取伺服器可連線的任何 HTTP(S) URL。
--allowed-grafana-urls：URL 覆寫的選用 Grafana 基礎 URL 精確比對允許清單，以逗號分隔。會回退至 GRAFANA_ALLOWED_URLS。需要 --allow-grafana-url-override；明確設定為空的旗標會停用繼承的清單。

呼叫端驗證（僅限 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，則會在啟動時遭拒。

Grafana URL 覆寫（僅限 streamable-http）：

[!WARNING] URL 覆寫允許 MCP 呼叫端選取對外 HTTP(S) 目的地。允許清單可限制 URL，但不會驗證呼叫端身分，也不會將權杖綁定至目標。

請部署在具備驗證功能的代理後方，由代理授權每個目標、替換用戶端提供的 URL 和權杖標頭，並提供相符的權杖。請限制伺服器的對外網路存取，只允許連線至核准的目的地。

若未設定允許清單，偽造的請求權杖可能導致請求傳送至任何可連線的 HTTP(S) 服務，包括內部服務和中繼資料服務。

設定 GRAFANA_ALLOW_URL_OVERRIDE=true（或 --allow-grafana-url-override）以啟用大型部署環境的選取功能。若要限制目的地，也請設定 GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana（或 --allowed-grafana-urls）。

在每個用來選取目標的 MCP 請求中傳送以下標頭：

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

若已設定 --server-auth-token，也請傳送 Authorization: Bearer <MCP caller token>。此標頭用於向 MCP 伺服器驗證身分，與用於所選 Grafana 執行個體的 X-Grafana-Service-Account-Token 不同。您的代理可以為每個執行個體傳送不同的 Grafana 權杖；伺服器絕不會在這些執行個體之間共用同一個已設定的權杖。已棄用的 X-Grafana-API-Key 標頭也可使用。若有 URL 標頭但沒有請求 Grafana 權杖，請求會遭拒。由於傳入請求包含權杖，請使用 TLS。

允許清單會比對完全相符的基礎 URL，包括配置、連接埠和路徑；不支援萬用字元。Grafana 驗證不是 SSRF 防護措施。

對於選取的 URL，伺服器不會使用 GRAFANA_SERVICE_ACCOUNT_TOKEN、GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE、GRAFANA_API_KEY、環境基本驗證、GRAFANA_EXTRA_HEADERS 或用戶端憑證。即使設定了 --tls-skip-verify，TLS 驗證仍會啟用；已設定的 CA 檔案仍會套用。明確從該請求轉送的標頭仍會生效。重新導向及其他超出所選基礎 URL 的 Grafana API 請求都會遭到封鎖。沒有 X-Grafana-URL 的請求會維持一般的 GRAFANA_URL 和環境憑證行為。此選項僅適用於 streamable HTTP。SSE 不會將每個請求的標頭傳遞至工具呼叫，因此無法使用此功能；在 SSE 中，所選 URL 會在沒有呼叫端權杖的情況下使用，導致呼叫失敗。

偵錯與記錄：

--debug：啟用偵錯模式，以詳細記錄 HTTP 請求/回應
--log-level：記錄層級（debug、info、warn、error）- 預設值：info

Grafana 用戶端選項：

--grafana-timeout：Grafana 用戶端請求的時間限制。接受 Go duration 字串（例如 10s、500ms）- 預設值：10s
--allow-cross-origin-redirects：允許對外 Grafana 用戶端重新導向至不同的配置、主機或連接埠。預設為 false；GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS 是環境變數的回退值。啟用此選項可能會將 Grafana 憑證傳送至重新導向目標。由請求選取的 Grafana URL 仍會固定至其所選目標。
--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 duration 字串（例如 500ms、5s）。預設值 0 會停用慢速請求記錄。請參閱慢速請求記錄一節。
--slow-request-log-level：慢速請求事件的記錄層級（info 或 warn）- 預設值：warn。

匿名使用統計資料：

--usage-stats：匿名使用統計資料回報：enabled、disabled 或 log（將原本會傳送的報告輸出至 stderr，但不傳送任何內容）。會覆寫 GRAFANA_USAGE_STATS 環境變數，而該變數又會覆寫 DO_NOT_TRACK；任何無法辨識的值都會停用回報。請參閱匿名使用統計資料一節。 工具設定：
--enabled-tools：以逗號分隔的啟用類別清單 - 預設：除 admin、agento11y、assistant、athena、clickhouse、cloudlogging、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 的資料；此防護要求使用具選擇性的串流選取器、限制有效時間範圍（包括 [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 呼叫的最大有效時間範圍，包括範圍向量持續時間 - 預設：24h。接受 Go 持續時間字串。0 會停用範圍檢查。環境變數備援：GRAFANA_LOKI_GUARDRAIL_MAX_RANGE。
--prometheus-guardrail-mode：適用於 query_prometheus、query_prometheus_histogram 及 run_panel_query 中 Prometheus 查詢的 Prometheus 查詢防護 - 預設：off。此防護會在查詢送達資料來源前，限制查詢的有效時間範圍及每個序列要求的點數。獨立的選擇器政策可選擇要求每個向量選取器都包含指標名稱以外的非空正向標籤條件；範例與限制請參閱選擇器政策。shadow 會記錄原本會被封鎖的查詢，但仍允許執行；enforce 則會拒絕這些查詢，並提供 LLM 可採取行動的改寫指引（run_panel_query 會在該面板結果的 errors 項目中回報此情況）。環境變數備援：GRAFANA_PROMETHEUS_GUARDRAIL_MODE。
--prometheus-guardrail-require-selective-labels：要求每個向量選取器都包含指標名稱以外的非空正向標籤條件。預設：false；獨立於範圍與點數預算，即使兩者皆為 0 也不受影響。僅在防護模式不是 off 時適用。環境變數備援：GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS。明確指定的 CLI 值（包括 false）會覆寫環境變數。
--prometheus-guardrail-max-range：單次 PromQL 查詢的最大有效時間範圍 - 預設：192h。有效範圍是查詢本身的時間範圍（即時查詢為零），加上運算式中最長的範圍向量或子查詢視窗；巢狀子查詢的範圍會累加，因此 max_over_time(rate(x[5m])[30d:1m]) 會讀作 30d5m。接受 Go 持續時間字串，因此請寫成 192h，而非 8d。0 會停用範圍檢查。環境變數備援：GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE。
--prometheus-guardrail-max-points：範圍查詢每個序列最多可要求的點數，floor(range / step) + 1 - 預設：11000，即 Prometheus 自身的每序列限制。指引會指出符合需求的最小 stepSeconds。0 會停用點數檢查。環境變數備援：GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS。

Prometheus 防護的限制：點數檢查會依據要求的解析度計算預算，而非序列數、樣本數或子查詢評估次數；Grafana 也可能會對齊範圍或加大步長。offset 和 @ 修飾詞會被忽略。$__rate_interval 和 $__range 等 Grafana 巨集會在測量運算式前先填入 Grafana 使用的值（$__rate_interval 是步長的四倍）。若防護仍無法解析運算式（例如包含 $window 等儀表板變數，或使用其他方言才接受的語法），則只會依據查詢本身的時間範圍和步長進行檢查，否則仍會執行。run_panel_query 沒有步長參數，因此會像 Grafana 一樣，針對較長的範圍加大其 1 分鐘步長，以維持在 11000 個點以內；若處於 enforce 模式，則會維持在較低的 --prometheus-guardrail-max-points 以內。
--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：停用事件工具
--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 下也要保留註冊，適用於寫入行為範圍足夠明確、可個別重新啟用的工具。若整個類別已停用，則不會生效。例如，--enable-write-tools=generate_deeplink 可讓 URL 縮短功能（shorten=true）在 --disable-write 下繼續運作，而 --enable-write-tools=alerting_rules_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-admin：停用管理工具
--disable-pyroscope：停用 Pyroscope 工具
--disable-navigation：停用導覽工具
--disable-rendering：停用轉譯工具（面板／儀表板圖片匯出）
--disable-snapshot：停用快照工具
--disable-cloudwatch：停用 CloudWatch 工具
--disable-cloudlogging：停用 Google Cloud Logging 工具
--disable-examples：停用查詢範例工具
--disable-sql：停用 SQL 資料來源工具（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL、BigQuery）。別名 --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

事件工具：

create_incident
add_activity_to_incident
update_incident

警示工具：

alerting_rules_write（建立、更新、刪除操作）
alerting_silences_write（建立、更新、刪除操作）
alerting_routing_write（create_contact_point 操作）

每個警示寫入工具都可透過 --enable-write-tools=<name> 個別保留。

OnCall 工具：

update_alert_group

註解工具：

create_annotation
update_annotation
delete_annotation

快照工具：

create_snapshot
delete_snapshot

導覽工具：

generate_deeplink（會忽略 shorten=true 並傳回完整 URL；傳入 --enable-write-tools=generate_deeplink 可保留 URL 縮短功能）

原始 SQL 查詢工具：

這些工具會直接執行你提供的任何查詢，不會先檢查查詢內容，因此只要資料來源憑證允許，就可能執行寫入操作 — query_sql 會執行 DROP TABLE，而 query_influxdb 會執行 DELETE。因此，唯讀模式會移除這些工具。若已知資料來源憑證為唯讀，請傳入 --enable-query 以保留這些工具。

query_sql
query_influxdb

Agent Observability 工具：

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

轉譯工具：

render_grafana_app

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
query_cloudwatch_logs

Google Cloud Logging 工具：

query_cloud_logging

Pyroscope 工具：

query_pyroscope

執行面板查詢工具：

run_panel_query

elasticsearch、quickwit、influxdb 和 runpanelquery 類別不包含其他內容，因此停用查詢時完全不會註冊任何工具。其他所有類別中的同類工具——list_prometheus_metric_names、list_loki_label_values、describe_sql_table、list_cloudwatch_metrics、list_cloud_logging_projects 等——仍可使用。

請注意，--disable-query 會控管查詢工具和 grafana_api_request 對 /api/ds/query 的 POST 路徑，但不會限制所有通往資料來源的路由。在唯讀模式下，只有啟用查詢工具時，grafana_api_request 才允許對 /api/ds/query 發出 POST（與原始 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_FILE 指向包含權杖的檔案路徑，而不必透過 GRAFANA_SERVICE_ACCOUNT_TOKEN 直接傳入權杖。每次收到請求時都會重新讀取檔案，因此輪替後的權杖會自動套用，無須重新啟動伺服器。

這在 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 標頭：**使用 streamable HTTP 傳輸時設定 X-Grafana-Org-Id（標頭優先於環境變數，因此您也可以設定預設組織）。

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

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

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

啟用後，每個工具都會接受選用的 orgId 引數，用來覆寫該次呼叫的連線組織（同時影響 X-Grafana-Org-Id 標頭，以及 app-platform 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 Proxy

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

URL 必須使用 socks5:// 或 socks5h:// 配置（Go 對兩者的處理方式相同：主機名稱解析會交由 Proxy 處理），且可包含認證資訊，例如 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"
      }
    }
  }
}

無效的 Proxy URL 會導致啟動錯誤；若執行階段建立 Proxy 連線失敗，伺服器會採取封閉失敗策略，而不會在未提示的情況下直接傳送 Grafana 流量。

轉送用戶端標頭（僅適用於 Streamable-HTTP）

當 MCP 伺服器位於處理 SSO 的閘道或反向 Proxy 後方（例如使用 OIDC 的 AWS ALB）時，必須將每位使用者的工作階段 Cookie 傳送至 Grafana，讓 Grafana 將請求與已驗證的使用者關聯。GRAFANA_FORWARD_HEADERS 環境變數可啟用此功能，方法是指定以逗號分隔的允許清單，列出要從傳入的 HTTP 請求複製到每個傳出 Grafana API 請求的標頭名稱。

此功能僅適用於使用 streamable-http（-t streamable-http）傳輸時。在 stdio 或 SSE 模式下不會生效。

範例：轉送工作階段 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 伺服器，但大多數使用者若要直接與 Claude Desktop 等 AI 助理整合，會希望使用 STDIO 模式：
  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 模式不受影響。請參閱呼叫端驗證。
  1. **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
```
  1. **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/v2/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 資料來源用戶端
事件管理用戶端
警示用戶端
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）不會公開 HTTP 伺服器，因此無法使用此端點。

匿名使用統計資料

伺服器可以向 Grafana Labs 回報自身的匿名使用統計資料：呼叫了哪些工具、其中有多少呼叫失敗，以及伺服器的設定方式。每份報告涵蓋一個伺服器程序，而非一位使用者或一段對話；每 4 小時傳送一次，並在關閉時再傳送一次。預設會啟用回報功能。若要選擇退出，請設定 --usage-stats=disabled、GRAFANA_USAGE_STATS=disabled 或 DO_NOT_TRACK=1。

絕不會傳送工具引數、資源名稱、查詢、日誌行、錯誤訊息或憑證。旗標只會記錄名稱，不會記錄值；Grafana 執行個體只會標示為 cloud 或 self_hosted，絕不會記錄 URL、主機名稱、堆疊代稱或組織。任何資料都不會依使用者、工作階段或用戶端區分：傳輸內容中沒有工作階段識別碼，也無法將工具呼叫歸屬至特定用戶端。

# 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`）
`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 推出期間如何解讀這些資料。

啟用 Prometheus 防護機制（--prometheus-guardrail-mode）時，四個計數器會以相同方式記錄其判定：

指標	類型	說明
`mcp_prometheus_guardrail_admitted_total`	Counter	通過所有已啟用檢查的查詢
`mcp_prometheus_guardrail_would_block_total`	Counter	在 `shadow` 模式下未通過檢查但仍執行的查詢（標籤：`reason`）
`mcp_prometheus_guardrail_blocked_total`	Counter	在 `enforce` 模式下遭拒的查詢（標籤：`reason`）
`mcp_prometheus_guardrail_fail_open_total`	Counter	防護機制無法剖析其運算式但仍予以放行的查詢（標籤：`reason`）

在 would_block 和 blocked 上，reason 為 range 或 points，並依第一個未通過的檢查（依序為 range、points）計數一次；在 fail_open 上則為 unparseable。沒有 backend 標籤：所有相容於 Prometheus 的後端都會執行相同檢查。

程式庫嵌入者應設定 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 會遵循語意慣例命名（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）。只要將 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT（或通用的 OTEL_EXPORTER_OTLP_ENDPOINT）指向遠端 gRPC 端點，並透過 OTEL_EXPORTER_OTLP_LOGS_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）提供驗證資訊，就能將日誌直接傳送至任何接受 OTLP/gRPC 的代管後端，例如 Grafana Cloud；設定方式與上述追蹤範例相同。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 匯出器規格。

若設定的 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 日誌串流，方法是在伺服器發出的每個原生 Loki 查詢中，以 AND 運算加入一組固定的 LogQL 標籤比對條件。當資料來源包含不得公開的串流（例如可能含有敏感資訊的日誌），但無法在 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-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 撰寫。工具版本和開發工作位於 mise.toml：安裝 mise，執行 mise install 取得固定版本的工具，並執行 mise tasks 列出工作。

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

mise run run

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

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

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

mise run build-image

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

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

若要改用 STDIO 模式，請覆寫傳輸設定：

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

測試

提供三種類型的測試：

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

mise run test-unit

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

mise run test

整合測試（需要 Docker 容器正在執行）：

mise run test-integration

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

mise run test-cloud

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

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

docker-compose up -d

如果你要新增工具，請為其新增整合測試。現有測試可作為良好的起點。

程式碼檢查

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

mise run lint

其中包含一個自訂檢查工具，用來檢查 jsonschema struct 標籤中未跳脫的逗號。description 欄位中的逗號必須使用 \\, 跳脫，以避免遭到靜默截斷。你可以只執行此檢查工具：

mise run lint-jsonschema

如需詳細資訊，請參閱 JSONSchema Linter 文件。

授權條款

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