Grafana MCP Server

公式

Grafanaインスタンス内のダッシュボードを検索し、インシデントを調査し、データソースにクエリを実行します。

GitHub

3.2k

ドキュメント

Grafana MCP サーバー

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 を使用します。
ダッシュボードの特定の部分のみが必要な場合は、JSONPath で get_dashboard_property を使用します。
完全なダッシュボード JSON が特に必要な場合を除き、get_dashboard_by_uid は避けてください。

データソース

データソース情報の一覧表示と取得: 設定されているすべてのデータソースを表示し、それぞれの詳細情報を取得します。
- サポートされているデータソースタイプ: 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 へのクエリ: Grafana マクロと変数置換をサポートして SQL クエリを実行します。

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 Enterprise プラグイン grafana-snowflake-datasource) を経由するため、認証は Grafana のデータソース設定によって処理され、資格情報が MCP サーバーに表示されることはありません。これは ClickHouse ツールで使用されているモデルと同じです。

Snowflake テーブルの一覧表示: INFORMATION_SCHEMA.TABLES 経由でテーブル (データベース、スキーマ、種類、行数、サイズを含む) を検出します。オプションのデータベース/スキーマフィルター。
テーブルスキーマの説明: Snowflake テーブルのカラム名、データ型、Null 許容性、デフォルト、コメントを取得します。
Snowflake へのクエリ: マクロと変数置換をサポートして SQL クエリを実行します。ログとトレースのための Snowflake のイベントテーブル (例: SNOWFLAKE.TELEMETRY.EVENTS) や、任意のユーザーテーブルのクエリに役立ちます。
- サポートされているマクロ: $__timeFilter(column)、$__timeFrom、$__timeTo、$__from、$__to (Unix ミリ秒)、$__interval (秒)、$__interval_ms、およびテンプレート変数置換用の ${varname}。

Elasticsearch/OpenSearch クエリ

注: Elasticsearch/OpenSearch ツールはデフォルトで無効です。有効にするには、elasticsearch を --enabled-tools フラグに追加してください。

Elasticsearch/OpenSearch へのクエリ: Lucene クエリ構文または Elasticsearch Query DSL を使用して、Elasticsearch または OpenSearch データソースに対して検索クエリを実行します。時間範囲によるフィルタリングと、ログ、メトリック、または任意のインデックス付きデータの取得をサポートします。ドキュメントをインデックス、ID、ソースフィールド、およびオプションの関連性スコアとともに返します。

Quickwit クエリ

注: Quickwit ツールはデフォルトで無効です。有効にするには、quickwit を --enabled-tools フラグに追加してください。

Quickwit へのクエリ: Lucene クエリ構文または部分的な Elasticsearch 互換の Query DSL を使用して、Quickwit データソースに対して検索クエリを実行します。時間範囲によるフィルタリングと、ログまたはその他のインデックス付きドキュメントの取得をサポートします。ドキュメントをインデックス、ID、ソースフィールド、およびオプションの関連性スコアとともに返します。

インシデント

インシデントの検索、作成、更新: 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 によって特定のアラートグループに関する詳細情報を取得します。

管理

注: 管理ツールはデフォルトで無効です。有効にするには、admin を --enabled-tools フラグに含めてください。

チームの一覧表示: Grafana で設定されているすべてのチームを表示します。
ユーザーの一覧表示: Grafana の組織内のすべてのユーザーを表示します。
すべてのロールの一覧表示: 委任可能なロールのオプションフィルター付きで、すべての Grafana ロールを一覧表示します。
ロール詳細の取得: UID によって特定の Grafana ロールの詳細を取得します。
ロールの割り当ての一覧表示: ロールに割り当てられているすべてのユーザー、チーム、サービスアカウントを一覧表示します。
ユーザーのロールの一覧表示: 1 人以上のユーザーに割り当てられているすべてのロールを一覧表示します。
チームのロールの一覧表示: 1 つ以上のチームに割り当てられているすべてのロールを一覧表示します。
リソースの権限の一覧表示: 特定のリソース (ダッシュボード、データソース、フォルダーなど) に定義されているすべての権限を一覧表示します。
Grafana リソースの説明: リソースタイプで利用可能な権限と割り当て機能を一覧表示します。

ディープリンクの生成: LLMによるURL推測に頼らず、Grafanaリソースへの正確なディープリンクURLを作成します。
- ダッシュボードリンク: UIDを使用してダッシュボードへの直接リンクを生成します（例: http://localhost:3000/d/dashboard-uid）
- パネルリンク: viewPanelパラメータを使用してダッシュボード内の特定のパネルへのリンクを作成します（例: http://localhost:3000/d/dashboard-uid?viewPanel=5）
- Exploreリンク: 事前設定されたデータソースでGrafana Exploreへのリンクを生成します（例: http://localhost:3000/explore?left={"datasource":"prometheus-uid"}）
- 時間範囲のサポート: リンクに時間範囲パラメータを追加します（from=now-1h&to=now）
- カスタムパラメータ: ダッシュボード変数や更新間隔などの追加のクエリパラメータを含めます

アノテーション

アノテーションの取得: フィルターを使用してアノテーションをクエリします。時間範囲、ダッシュボードUID、タグ、マッチモードをサポートします。
アノテーションの作成: ダッシュボードまたはパネルに新しいアノテーションを作成します。
Graphiteアノテーションの作成: Graphite形式を使用してアノテーションを作成します（what、when、tags、data）。
アノテーションの更新: 既存のアノテーションのすべてのフィールドを置き換えます（完全更新）。
アノテーションのパッチ: アノテーションの特定のフィールドのみを更新します（部分更新）。
アノテーションタグの取得: オプションのフィルタリングで利用可能なアノテーションタグを一覧表示します。

スナップショット

スナップショットの一覧: オプションのクエリと制限フィルターを使用してダッシュボードスナップショットを一覧表示します。
スナップショットの取得: スナップショットキーでスナップショットのメタデータとダッシュボードペイロードを取得します。
スナップショットの作成: 完全なダッシュボードペイロードからダッシュボードスナップショットを作成します。オプションで有効期限と外部スナップショットオプションを指定できます。
スナップショットの削除: スナップショットキーでスナップショットを削除します。

レンダリング

パネルまたはダッシュボード画像の取得: Grafanaダッシュボードパネルまたはダッシュボード全体をPNG画像としてレンダリングします。レポート、アラート、プレゼンテーションで使用するためにbase64エンコードされたデータとして画像を返します。寸法、時間範囲、テーマ、スケール、ダッシュボード変数のカスタマイズをサポートします。また、オプションのprovisioningPreviewパラメータを介して、プロビジョニングリポジトリブランチ（例：git-sync PRプレビュー）からまだ適用されていないダッシュボードのレンダリングもサポートします。
- 注意: Grafana Image Renderer サービスがインストールおよび設定されている必要があります。

プロビジョニング

プロビジョニングリポジトリの一覧: このGrafanaインスタンスに設定されているプロビジョニングリポジトリ（例：git-syncソース）を一覧表示し、各リポジトリのスラッグとそのソースURL、ブランチ、パス、同期状態、ヘルスを返します。
プロビジョニングファイルの検証: 指定されたブランチまたはコミットのプロビジョニングリポジトリからファイルをドライラン適用します。受け入れられるかどうか、リソースアクション（作成/更新）、ターゲットリソースタイプ、構造化された検証エラーを返します。これはGrafanaのPRコメンターが使用するものと同じアドミッションサーフェスです。

ツールのリストは設定可能であるため、MCPクライアントで利用可能にするツールを選択できます。これは、特定の機能を使用しない場合や、コンテキストウィンドウを占有しすぎたくない場合に便利です。ツールのカテゴリを無効にするには、サーバー起動時に--disable-<category>フラグを使用します。たとえば、 OnCallツールを無効にするには--disable-oncallを使用し、ナビゲーションディープリンク生成を無効にするには--disable-navigationを使用します。

RBAC権限

各ツールが正しく機能するには、特定のRBAC権限が必要です。MCPサーバーのサービスアカウントを作成する際は、使用する予定のツールに基づいて必要な権限が付与されていることを確認してください。記載されている権限は最低限必要なアクションです。ユースケースに応じて、適切なスコープ（例：datasources:*、dashboards:*、folders:*）も必要になる場合があります。

ヒント: Grafana RBACに精通していない場合や、多くの細かいスコープを設定する代わりに、より迅速で簡単なセットアップを希望する場合は、サービスアカウントにEditorなどの組み込みロールを割り当てることができます。Editorロールは、ほとんどのMCPサーバー操作を許可する広範な読み取り/書き込みアクセスを付与します。手動で適用するスコープよりも粒度が低い（したがって制限が緩い）ため、厳密な最小権限アクセスよりも利便性が重要な場合にのみ使用してください。

注意: Grafana IncidentおよびSiftツールは、きめ細かいRBAC権限ではなく、基本的なGrafanaロールを使用します。

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*	1 つ以上のダッシュボードパネルクエリを実行	`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_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*	テーブルスキーマ（カラムタイプ、NULL許容、デフォルト、コメント）を取得	`datasources:query`	`datasources:uid:*`
`query_snowflake`	Snowflake*	マクロ/変数置換を使用したSQLクエリを実行	`datasources:query`	`datasources:uid:*`
`alerting_manage_rules`	アラート	アラートルールの管理（一覧表示、取得、バージョン、作成、更新、削除）	`alert.rules:read` + `alert.rules:write` for mutations	`folders:*` or `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:*` or `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:*` or `dashboards:uid:abc123`
`get_snapshot`	スナップショット	スナップショットキーでスナップショットメタデータとダッシュボードペイロードを取得	`dashboards:read`	`dashboards:*` or `dashboards:uid:abc123`
`create_snapshot`	スナップショット	完全なダッシュボードペイロードからダッシュボードスナップショットを作成	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`delete_snapshot`	スナップショット	スナップショットキーでダッシュボードスナップショットを削除	`dashboards:write`	`dashboards:*` or `dashboards:uid:abc123`
`get_panel_image`	レンダリング	保存されたダッシュボードまたはパネル、あるいはリポジトリブランチからのプロビジョニングプレビューをPNG画像としてレンダリング	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	プロビジョニング	プロビジョニングリポジトリ（例：git-syncソース）をソースURL、ブランチ、同期状態、ヘルスとともに一覧表示	`provisioning.repositories:read`	N/A
* デフォルトでは無効です。有効にするには `--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 の duration 文字列を受け入れます (例: 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 の場合は、以下の設定例で http://localhost:3000 の代わりにインスタンス URL (例: https://myinstance.grafana.net) を使用してください。

サービスアカウントトークン認証を使用する場合は、使用したいツールに十分な権限を持つサービスアカウントを Grafana で作成し、サービスアカウントトークンを生成して、設定ファイルで使用するためにクリップボードにコピーします。サービスアカウントトークンの作成の詳細については、Grafana サービスアカウントのドキュメントに従ってください。ヒント: きめ細かい RBAC スコープの設定に慣れていない場合は、よりシンプルな (ただし制限は緩い) オプションとして、組み込みの Editor ロールをサービスアカウントに割り当てることです。これにより、ほとんどの MCP サーバー操作をカバーする広範な読み取り/書き込みアクセスが付与されます。利便性が厳密な最小権限の要件よりも優先される場合に使用してください。

注意: 環境変数 GRAFANA_API_KEY は非推奨であり、将来のバージョンで削除される予定です。代わりに GRAFANA_SERVICE_ACCOUNT_TOKEN を使用するように移行してください。古い変数名は下位互換性のために引き続き動作しますが、非推奨の警告が表示されます。

ファイルからサービスアカウントトークンを読み取る

GRAFANA_SERVICE_ACCOUNT_TOKEN を介してトークンをインラインで渡す代わりに、トークンを含むファイルパスを GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE に指定できます。ファイルはリクエストごとに新しく読み取られるため、ローテーションされたトークンはサーバーを再起動せずに自動的に取得されます。

これは、ボリュームとしてマウントされた Secret が、基になる Secret が変更されたときにインプレースで更新される Kubernetes で特に役立ちます (通常は約 1 分以内)。トークン値に基づいてキーが設定されるリクエストごとのクライアントキャッシュと組み合わせることで、ローテーションされたトークンは、Pod の再起動やダウンタイムなしで透過的に新しいクライアントを生成します。

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

ファイルの内容から前後の空白 (末尾の改行を含む) はトリミングされます。GRAFANA_SERVICE_ACCOUNT_TOKEN と GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE の両方が設定されている場合は、インライントークンが優先されます。

マルチ組織サポート

対話する組織を指定するには、次のいずれかを使用します。

環境変数: GRAFANA_ORG_ID を数値の組織 ID に設定します
HTTP ヘッダー: SSE または streamable HTTP トランスポートを使用する場合は X-Grafana-Org-Id を設定します (ヘッダーが環境変数よりも優先されます。つまり、デフォルトの組織も設定できます)。

組織 ID が提供されると、MCP サーバーは Grafana へのすべてのリクエストに X-Grafana-Org-Id ヘッダーを設定し、指定された組織コンテキスト内で操作が実行されるようにします。

組織 ID を使用した例:

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

カスタム HTTP ヘッダー

GRAFANA_EXTRA_HEADERS 環境変数を使用して、任意の HTTP ヘッダーをすべての Grafana API リクエストに追加できます。値は、ヘッダー名を値にマッピングする JSON オブジェクトである必要があります。

カスタムヘッダーを使用した例:

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

クライアントからのヘッダー転送 (SSE/Streamable-HTTP のみ)

MCP サーバーが SSO を処理するゲートウェイまたはリバースプロキシ (例: OIDC を使用する AWS ALB) の背後で実行されている場合、各ユーザーのセッション Cookie が Grafana に到達し、リクエストを認証されたユーザーに関連付けることができる必要があります。GRAFANA_FORWARD_HEADERS 環境変数は、受信 HTTP リクエストから送信 Grafana API リクエストにコピーするヘッダー名のカンマ区切り許可リストを指定することで、これを有効にします。

これは、SSE (-t sse) または streamable-http (-t streamable-http) トランスポートを使用する場合にのみ適用されます。stdio モードでは効果がありません。

例: セッション Cookie を転送する

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

カンマで区切ることで、複数のヘッダーを転送できます。

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

転送されたヘッダーは、GRAFANA_EXTRA_HEADERS で定義されたヘッダーとマージされます。ヘッダー名が両方に存在する場合、そのリクエストでは受信リクエストからの値が優先されます。

mcp-grafana をインストールするには、いくつかのオプションがあります。
- uvx (推奨): uv がインストールされている場合、追加のセットアップは不要です。uvx が自動的にサーバーをダウンロードして実行します。
```
uvx mcp-grafana
```
- Docker イメージ: Docker Hub から事前にビルドされた Docker イメージを使用します。
  
  重要: Docker イメージのエントリポイントは、デフォルトで SSE モードで MCP サーバーを実行するように設定されていますが、ほとんどのユーザーは Claude Desktop などの AI アシスタントとの直接統合のために STDIO モードを使用することをお勧めします。
  1. STDIO モード: stdio モードの場合は、-t stdio でデフォルトを明示的に上書きし、stdin を開いたままにするために -i フラグを含める必要があります。
```
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 チャートを使用します。
```
helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp
```

クライアント設定ファイルにサーバー設定を追加します。たとえば、Claude Desktop の場合:

uvx を使用する場合:

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

バイナリを使用する場合:

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

注意: Claude Desktop で Error: spawn mcp-grafana ENOENT が表示される場合は、mcp-grafana へのフルパスを指定する必要があります。

Docker を使用する場合:

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

注意: -t stdio 引数は、Docker イメージのデフォルトの SSE モードを上書きするため、ここでは必須です。

リモート MCP サーバーでの VSCode の使用

VSCode を使用し、SSE モードで MCP サーバーを実行している場合 (トランスポートを上書きせずに Docker イメージを使用する場合のデフォルト)、.vscode/settings.json に以下が含まれていることを確認してください。

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

サーバー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>"
      }
    }
  }
}

注意: 標準設定と同様に、DockerイメージでデフォルトのSSEモードを上書きするには -t stdio 引数が必要です。

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 に接続する場合、不正な形式の X-Grafana-URL ヘッダーを400 Bad Requestで拒否するために ValidateGrafanaURLMiddleware をインストールします（バイナリの動作と一致）。

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サーバーがHTTPの代わりにHTTPSを提供するように設定できます。これは、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

これにより、MCPサーバーがHTTPSポート8443で起動します。クライアントは http://localhost:8000/ の代わりに https://localhost:8443/ に接続します。

サーバー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サーバーは、OTel MCPセマンティック規約に従い、Prometheusメトリクス、OpenTelemetry分散トレーシング、およびOpenTelemetryログエクスポートをサポートしています。トレーシングとログエクスポートは、標準の 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.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 が設定されている場合、サーバーは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"}

これは通常、Grafana 9.0より前のバージョンを使用していることを示します。/datasources/uid/{uid} APIエンドポイントはGrafana 9.0で導入されたため、それ以前のバージョンではデータソース操作が失敗します。

解決策: Grafanaインスタンスをバージョン9.0以降にアップグレードして、この問題を解決してください。

開発

貢献を歓迎します！提案や改善点がある場合は、Issueを開くかプルリクエストを送信してください。

このプロジェクトは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

テスト

利用可能なテストは3種類あります。

ユニットテスト（外部依存関係不要）:

make test-unit

次のコマンドでもユニットテストを実行できます。

make test

統合テスト（Dockerコンテナの起動が必要）:

make test-integration

クラウドテスト（クラウドGrafanaインスタンスと認証情報が必要）:

make test-cloud

注意: クラウドテストはCIで自動的に設定されます。ローカル開発では、独自のGrafana Cloudインスタンスと認証情報を設定する必要があります。

より包括的な統合テストには、ポート3000でローカルにGrafanaインスタンスが実行されている必要があります。Docker Composeで起動できます。

docker-compose up -d

統合テストは次のコマンドで実行できます。

make test-all

ツールを追加する場合は、それらの統合テストを追加してください。既存のテストが良い出発点となるはずです。

リンティング

コードをリントするには、以下を実行します。

make lint

これには、jsonschema 構造体タグ内のエスケープされていないカンマをチェックするカスタムリンターが含まれています。description フィールドのカンマは、サイレントトランケーションを防ぐために \\, でエスケープする必要があります。このリンターのみを実行するには、以下を使用します。

make lint-jsonschema

詳細については、JSONSchemaリンターのドキュメントを参照してください。

ライセンス

このプロジェクトはApache License, Version 2.0の下でライセンスされています。