Grafana MCP Server

官方

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

GitHub
3.2k

文件

Grafana MCP 伺服器

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

一個用於 Grafana 的 模型上下文協定 (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 取得儀表板： 使用其唯一識別碼擷取完整的儀表板詳細資訊。警告：大型儀表板可能會消耗大量的上下文視窗空間。
  • 取得儀表板摘要： 取得儀表板的緊湊概覽，包括標題、面板數量、面板類型、變數和中繼資料，而不包含完整的 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 日誌和指標： 對 Loki 資料來源使用 LogQL 執行日誌查詢和指標查詢。
  • 查詢 Loki 中繼資料： 從 Loki 資料來源擷取標籤名稱、標籤值和串流統計資料。
  • 查詢 Loki 模式： 擷取 Loki 偵測到的日誌模式，以識別常見的日誌結構和異常。

InfluxDB 查詢

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

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

ClickHouse 查詢

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

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

CloudWatch 查詢

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

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

Graphite 查詢

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

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

Athena 查詢

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

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

Snowflake 查詢

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

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

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

Elasticsearch/OpenSearch 查詢

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

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

Quickwit 查詢

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

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

事件

  • 搜尋、建立和更新事件： 管理 Grafana Incident 中的事件，包括搜尋、建立和新增活動至事件。

Sift 調查

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

警報

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

Grafana OnCall

  • 列出和管理排程： 在 Grafana OnCall 中檢視和管理待命排程。
  • 取得班次詳細資訊： 擷取特定待命班次的詳細資訊。
  • 取得目前待命使用者： 查看目前有哪些使用者在排程中待命。
  • 列出團隊和使用者： 檢視所有 OnCall 團隊和使用者。
  • 列出警報群組： 按各種條件（包括狀態、整合、標籤和時間範圍）檢視和篩選來自 Grafana OnCall 的警報群組。
  • 取得警報群組詳細資訊： 透過其 ID 擷取特定警報群組的詳細資訊。

管理

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

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

導覽

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

註釋

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

快照

  • 列出快照： 列出儀表板快照，可選擇性使用查詢和數量限制篩選。
  • 取得快照： 透過快照金鑰擷取快照中繼資料和儀表板內容。
  • 建立快照： 從完整的儀表板內容建立儀表板快照，可選擇性設定到期時間和外部快照選項。
  • 刪除快照： 透過快照金鑰刪除快照。

渲染

  • 取得面板或儀表板圖片： 將 Grafana 儀表板面板或完整儀表板渲染為 PNG 圖片。以 base64 編碼資料回傳圖片，用於報告、警示或簡報。支援自訂尺寸、時間範圍、主題、縮放比例和儀表板變數。也支援透過可選的 provisioningPreview 參數，從佈建儲存庫分支（例如 git-sync PR 預覽）渲染尚未套用的儀表板。

佈建

  • 列出佈建儲存庫： 列出為此 Grafana 執行個體設定的佈建儲存庫（例如 git-sync 來源），回傳每個儲存庫的 slug 及其來源網址、分支、路徑、同步狀態和健康狀況。
  • 驗證佈建檔案： 對來自佈建儲存庫指定分支或提交的檔案進行試執行套用。回傳是否會被接受、資源動作（建立/更新）、目標資源類型，以及任何結構化驗證錯誤——這與 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 權限：

  • Viewer 角色： 唯讀操作所需（列出事件、取得調查）
  • Editor 角色： 寫入操作所需（建立事件、修改調查）

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

RBAC 範圍

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

常見範圍模式：

  • 廣泛存取： 使用 * 萬用字元進行組織範圍的存取

    • datasources:* - 存取所有資料來源
    • dashboards:* - 存取所有儀表板
    • folders:* - 存取所有資料夾
    • teams:* - 存取所有團隊

  • 限制存取： 使用特定的 UID 或 ID 將存取限制在個別資源

    • datasources:uid:prometheus-uid - 僅存取特定的 Prometheus 資料來源
    • dashboards:uid:abc123 - 僅存取 UID 為 abc123 的儀表板
    • folders:uid:xyz789 - 僅存取 UID 為 xyz789 的資料夾
    • teams:id:5 - 僅存取 ID 為 5 的團隊
    • global.users:id:123 - 僅存取 ID 為 123 的使用者

範例：

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

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

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

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

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

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

工具| 工具 | 類別 | 說明 | 必要的 RBAC 權限 | 必要的範圍 |

| --------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | --------------------------------------------------- | | list_teams | 管理員 | 列出所有團隊 | teams:read | teams:* 或 teams:id:1 | | list_users_by_org | 管理員 | 列出組織中的所有使用者 | users:read | global.users:* 或 global.users:id:123 | | list_all_roles | 管理員 | 列出所有 Grafana 角色 | roles:read | roles:* | | get_role_details | 管理員 | 取得 Grafana 角色的詳細資訊 | roles:read | roles:uid:editor | | get_role_assignments | 管理員 | 列出角色的指派 | roles:read | roles:uid:editor | | list_user_roles | 管理員 | 列出使用者的角色 | roles:read | global.users:id:123 | | list_team_roles | 管理員 | 列出團隊的角色 | roles:read | teams:id:7 | | get_resource_permissions | 管理員 | 列出資源的權限 | permissions:read | dashboards:uid:abcd1234 | | get_resource_description | 管理員 | 描述 Grafana 資源類型 | permissions:read | dashboards:* | | search_dashboards | 搜尋 | 搜尋儀表板 | dashboards:read | dashboards:* 或 dashboards:uid:abc123 | | get_dashboard_by_uid | 儀表板 | 透過 uid 取得儀表板 | dashboards:read | dashboards:uid:abc123 | | update_dashboard | 儀表板 | 更新或建立新的儀表板 | dashboards:create、dashboards:write | dashboards:*、folders:* 或 folders:uid:xyz789 | | get_dashboard_panel_queries | 儀表板 | 從儀表板取得面板標題、查詢、資料來源 UID 和類型 | dashboards:read | dashboards:uid:abc123 | | run_panel_query | RunPanelQuery* | 執行一個或多個儀表板面板查詢 | dashboards:read、datasources:query | dashboards:uid:*、datasources:uid:* | | get_dashboard_property | 儀表板 | 使用 JSONPath 表達式提取儀表板的特定部分 | dashboards:read | dashboards:uid:abc123 | | get_dashboard_summary | 儀表板 | 取得儀表板的精簡摘要，不含完整 JSON | dashboards:read | dashboards:uid:abc123 | | list_datasources | 資料來源 | 列出資料來源 | datasources:read | datasources:* | | get_datasource | 資料來源 | 透過 UID 或名稱取得資料來源 | datasources:read | datasources:uid:prometheus-uid | | get_query_examples | 範例* | 取得資料來源類型的範例查詢 | datasources:read | datasources:* | | query_prometheus | Prometheus | 對 Prometheus 資料來源執行查詢 | datasources:query | datasources:uid:prometheus-uid | | list_prometheus_metric_metadata | Prometheus | 列出指標中繼資料 | datasources:query | datasources:uid:prometheus-uid | | list_prometheus_metric_names | Prometheus | 列出可用的指標名稱 | datasources:query | datasources:uid:prometheus-uid | | list_prometheus_label_names | Prometheus | 列出符合選擇器的標籤名稱 | datasources:query | datasources:uid:prometheus-uid | | list_prometheus_label_values | Prometheus | 列出特定標籤的值 | datasources:query | datasources:uid:prometheus-uid | | query_prometheus_histogram | Prometheus | 計算直方圖百分位數值 | datasources:query | datasources:uid:prometheus-uid | | list_incidents | 事件 | 列出 Grafana Incident 中的事件 | 檢視者角色 | N/A | | create_incident | 事件 | 在 Grafana Incident 中建立事件 | 編輯者角色 | N/A | | add_activity_to_incident | 事件 | 在 Grafana Incident 中新增活動項目至事件 | 編輯者角色 | N/A | | get_incident | 事件 | 透過 ID 取得單一事件 | 檢視者角色 | N/A | | query_loki_logs | Loki | 使用 LogQL 查詢和擷取日誌（日誌或指標查詢） | datasources:query | datasources:uid:loki-uid | | list_loki_label_names | Loki | 列出日誌中所有可用的標籤名稱 | datasources:query | datasources:uid:loki-uid | | list_loki_label_values | Loki | 列出特定日誌標籤的值 | datasources:query | datasources:uid:loki-uid | | query_loki_stats | Loki | 取得日誌串流的統計資料 | datasources:query | datasources:uid:loki-uid | | query_loki_patterns | Loki | 查詢偵測到的日誌模式以識別常見結構 | datasources:query | datasources:uid:loki-uid | | analyze_loki_labels | Loki | 稽核 Loki 標籤策略（即時或靜態），並可選擇診斷查詢效能 | datasources:query | datasources:uid:loki-uid | | suggest_loki_alloy_label_config | 設定 | 產生強制執行已核准標籤的 Alloy loki.process 片段 | N/A | N/A | | query_influxdb | InfluxDB | 使用 InfluxQL (v1) 或 Flux (v2) 查詢 InfluxDB | datasources:query | datasources:uid:influxdb-uid | | list_clickhouse_tables | ClickHouse* | 列出 ClickHouse 資料庫中的表格 | datasources:query | datasources:uid:* | | describe_clickhouse_table | ClickHouse* | 取得表格結構描述及欄位類型 | datasources:query | datasources:uid:* | | query_clickhouse | ClickHouse* | 使用巨集替換執行 SQL 查詢 | datasources:query | datasources:uid:* | | list_cloudwatch_namespaces | CloudWatch* | 列出可用的 AWS CloudWatch 命名空間 | datasources:query | datasources:uid:* | | list_cloudwatch_metrics | CloudWatch* | 列出命名空間中的指標 | datasources:query | datasources:uid:* | | list_cloudwatch_dimensions | CloudWatch* | 列出指標的維度 | datasources:query | datasources:uid:* | | query_cloudwatch | CloudWatch* | 執行 CloudWatch 指標查詢 | datasources:query | datasources:uid:* | | list_athena_catalogs | Athena* | 列出可用的 Athena 資料目錄 | datasources:query | datasources:uid:* | | list_athena_databases | Athena* | 列出 Athena 目錄中的資料庫 | datasources:query | datasources:uid:* | | list_athena_tables | Athena* | 列出 Athena 資料庫中的資料表 | datasources:query | datasources:uid:* | | describe_athena_table | Athena* | 取得 Athena 資料表的欄位名稱 | datasources:query | datasources:uid:* | | query_athena | Athena* | 使用巨集替換執行 SQL 查詢 | datasources:query | datasources:uid:* | | query_elasticsearch | Elasticsearch/OpenSearch* | 使用 Lucene 語法或 Query DSL 查詢 Elasticsearch 或 OpenSearch | datasources:query | datasources:uid:datasource-uid | | query_quickwit | Quickwit* | 使用 Lucene 語法或 Query DSL 查詢 Quickwit | datasources:query | datasources:uid:quickwit-uid | | list_snowflake_tables | Snowflake* | 透過 INFORMATION_SCHEMA 列出 Snowflake 資料庫/結構描述中的資料表 | datasources:query | datasources:uid:* | | describe_snowflake_table | Snowflake* | 取得資料表結構描述（欄位類型、可為空、預設值、註解） | datasources:query | datasources:uid:* | | query_snowflake | Snowflake* | 使用巨集/變數替換執行 SQL 查詢 | datasources:query | datasources:uid:* | | alerting_manage_rules | 警示 | 管理警示規則（列出、取得、版本、建立、更新、刪除） | alert.rules:read + alert.rules:write（用於變更） | folders:* 或 folders:uid:alerts-folder | | alerting_manage_routing | 警示 | 管理通知政策、聯絡點和時間間隔 | alert.notifications:read | 全域範圍 | | list_oncall_schedules | OnCall | 從 Grafana OnCall 列出排班表 | grafana-oncall-app.schedules:read | 外掛特定範圍 | | get_oncall_shift | OnCall | 取得特定 OnCall 班次的詳細資料 | grafana-oncall-app.schedules:read | 外掛特定範圍 | | get_current_oncall_users | OnCall | 取得特定排班表目前的值班人員 | grafana-oncall-app.schedules:read | 外掛特定範圍 | | list_oncall_teams | OnCall | 從 Grafana OnCall 列出團隊 | grafana-oncall-app.user-settings:read | 外掛特定範圍 | | list_oncall_users | OnCall | 從 Grafana OnCall 列出使用者 | grafana-oncall-app.user-settings:read | 外掛特定範圍 | | list_alert_groups | OnCall | 從 Grafana OnCall 列出警示群組，並提供篩選選項 | grafana-oncall-app.alert-groups:read | 外掛特定範圍 | | get_alert_group | OnCall | 透過 ID 從 Grafana OnCall 取得特定警示群組 | grafana-oncall-app.alert-groups:read | 外掛特定範圍 | | get_sift_investigation | Sift | 透過 UUID 擷取現有的 Sift 調查 | 檢視者角色 | N/A | | get_sift_analysis | Sift | 從 Sift 調查中擷取特定分析 | 檢視者角色 | N/A | | list_sift_investigations | Sift | 擷取 Sift 調查清單，可選擇限制數量 | 檢視者角色 | N/A | | find_error_pattern_logs | Sift | 在 Loki 日誌中尋找異常的錯誤模式。 | 編輯者角色 | N/A | | find_slow_requests | Sift | 從相關的 Tempo 資料來源中尋找緩慢的請求。 | 編輯者角色 | N/A | | 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 | 取得指定實體的斷言摘要 | 外掛特定權限 | 外掛特定範圍 | | generate_deeplink | 導覽 | 為 Grafana 資源產生準確的深層連結 URL | 無（唯讀 URL 產生） | N/A | | get_annotations | 註解 | 使用篩選條件擷取註解 | annotations:read | annotations:* 或 annotations:id:123 | | create_annotation | 註解 | 建立新的註解（標準或 Graphite 格式） | annotations:write | annotations:* | | update_annotation | 註解 | 更新註解的特定欄位（部分更新） | annotations:write | 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 | 不適用 | * 預設為停用。將類別加入 --enabled-tools 即可啟用。

CLI 旗標參考

mcp-grafana 執行檔支援多種命令列旗標進行設定：

傳輸選項：

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

除錯與記錄：

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

可觀測性：

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

工作階段管理：

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

工具設定：

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

唯讀模式

--disable-write 旗標提供了一種以唯讀模式執行 MCP 伺服器的方式，防止對您的 Grafana 執行個體進行任何寫入操作。這適用於您希望提供安全、唯讀存取的情境，例如：

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

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

儀表板工具：

  • update_dashboard

資料夾工具：

  • create_folder

事件工具：

  • create_incident
  • add_activity_to_incident

警示工具：

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

註解工具：

  • create_annotation
  • update_annotation

Sift 工具：

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

快照工具：

  • create_snapshot
  • delete_snapshot

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

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

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

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

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

使用方式

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

  1. 如果使用服務帳戶權杖驗證，請在 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 標頭： 使用 SSE 或 streamable HTTP 傳輸時設定 X-Grafana-Org-Id（標頭優先於環境變數 - 這表示您也可以設定預設組織）。

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

包含組織 ID 的範例：

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

自訂 HTTP 標頭

您可以使用 GRAFANA_EXTRA_HEADERS 環境變數，將任意 HTTP 標頭新增至所有 Grafana API 請求。該值應為一個將標頭名稱對應到值的 JSON 物件。

包含自訂標頭的範例：

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

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

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

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

範例：轉送工作階段 Cookie

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

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

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

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

  1. 您有多種選項可以安裝 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
      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> 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> 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> \
  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

  2. 將伺服器設定新增至您的客戶端設定檔。例如，對於 Claude Desktop：

    如果使用 uvx：

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

    如果使用執行檔：

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

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

如果使用 Docker：

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

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

搭配遠端 MCP 伺服器使用 VSCode

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

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

針對使用伺服器 TLS 憑證的 HTTPS 可串流 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)

在連接您自己的 HTTP 伺服器時進行 URL 驗證：

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

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

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

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

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

伺服器 TLS 設定（僅限可串流 HTTP 傳輸）

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

伺服器支援下列用於可串流 HTTP 傳輸的 TLS 設定選項：

  • --server.tls-cert-file：用於伺服器 HTTPS 的 TLS 憑證檔案路徑（TLS 所需）
  • --server.tls-key-file：用於伺服器 HTTPS 的 TLS 私密金鑰檔案路徑（TLS 所需）

注意：這些旗標與上面記錄的用戶端 TLS 旗標完全分開。用戶端 TLS 旗標設定 MCP 伺服器如何連接到 Grafana，而這些伺服器 TLS 旗標則設定在使用可串流 HTTP 傳輸時，用戶端如何連接到 MCP 伺服器。

使用 HTTPS 可串流 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）或可串流 HTTP（-t streamable-http）傳輸時，MCP 伺服器會在 /healthz 公開一個健康檢查端點。此端點可供負載平衡器、監控系統或協調平台使用，以驗證伺服器是否正在執行並接受連線。

端點： GET /healthz

回應：

  • 狀態碼：200 OK
  • 主體：ok

使用範例：

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

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

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

可觀測性

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

注意： mcp-grafana 目前僅支援用於追蹤和日誌的 OTLP/gRPC 傳輸。OTEL_EXPORTER_OTLP_PROTOCOL（及其 _TRACES_PROTOCOL / _LOGS_PROTOCOL 變體）不會被採用——無論如何都會使用 gRPC。

指標

使用 SSE 或可串流 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直方圖MCP 操作的持續時間（標籤：mcp_method_name、gen_ai_tool_name、error_type、network_transport、mcp_protocol_version）
mcp_server_session_duration_seconds直方圖MCP 用戶端工作階段的持續時間（標籤：network_transport、mcp_protocol_version）
http_server_request_duration_seconds直方圖HTTP 伺服器請求的持續時間（來自 otelhttp）

注意： 指標僅在使用 SSE 或可串流 HTTP 傳輸時可用。使用 stdio 傳輸時不可用。

慢速請求記錄

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

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

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

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

日誌事件帶有以下結構化屬性：

屬性說明
mcp.methodMCP 方法（例如 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 後，伺服器會透過 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

工具調用跨度遵循 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 橋接器會自動附加來自活動跨度的 trace_id 和 span_id，因此日誌記錄會與伺服器已發出的追蹤相關聯。

啟用 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 收集器是可選的——對於扇出、批次處理或多後端路由很有用，但不是必需的。

特定訊號的變體 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 匯出器規範 以取得完整清單和優先順序規則。

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

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

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

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

疑難排解

Grafana 版本相容性

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

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

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

解決方案： 將您的 Grafana 執行個體升級到 9.0 或更高版本以解決此問題。

開發

歡迎貢獻！如果您有任何建議或改進，請開啟一個議題或提交拉取請求。

此專案以 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

測試

提供三種類型的測試：

  1. 單元測試（無需外部依賴項）：
make test-unit

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

make test
  1. 整合測試（需要 Docker 容器已啟動並執行）：
make test-integration
  1. 雲端測試（需要雲端 Grafana 執行個體和憑證）：
make test-cloud

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

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

docker-compose up -d

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

make test-all

如果您要新增更多工具，請為它們新增整合測試。現有的測試應該是一個很好的起點。

程式碼檢查

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

make lint

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

make lint-jsonschema

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

授權

此專案依據 Apache License, Version 2.0 授權。