Grafana

公式

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

GitHub

3.4k

Grafana MCPで何ができますか？

ダッシュボードの検索と検査 — search_dashboards と get_dashboard_summary を使用して、ダッシュボードを検索し、完全なJSONなしでコンパクトな概要を取得します。
Prometheus と Loki のクエリ — データソースに対して PromQL および LogQL クエリを実行し、メタデータやヒストグラムのパーセンタイルも含めて取得します。
アラートの管理 — アラートルールの一覧表示、作成、更新、削除に加え、通知ポリシーと連絡先の表示を行います。
ディープリンクの生成 — ナビゲーションツールを使用して、時間範囲を含むダッシュボード、パネル、Explore への正確な URL を作成します。
パネルクエリの実行 — run_panel_query を使用して、カスタムの時間範囲と変数でダッシュボードパネルのクエリを実行します。

ドキュメント

Grafana MCP サーバー

Grafana 用の Model Context Protocol (MCP) サーバーです。

Grafana インスタンスとその周辺エコシステムへのアクセスを提供します。

クイックスタート

uv が必要です。MCP クライアント設定（例: Claude Desktop、Cursor）に以下を追加してください:

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

Grafana Cloud の場合は、GRAFANA_URL をインスタンス URL（例: https://myinstance.grafana.net）に置き換えてください。Docker、バイナリ、Helm を含むその他のインストールオプションについては、Usage を参照してください。

要件

フル機能を利用するには 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 render API クエリを実行します。
Graphite メトリックの一覧表示: Graphite メトリックパスを参照および検出します。
Graphite タグの一覧表示: 利用可能な Graphite タグとタグ値を一覧表示します。
Graphite 密度のクエリ: 指定されたパターンの Graphite メトリック密度をクエリします。

Athena クエリ

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

Athena カタログの一覧表示: 利用可能なデータカタログ（例: AwsDataCatalog、Iceberg コネクタ）を検出します。
Athena データベースの一覧表示: Athena カタログ内のデータベースを一覧表示します。
Athena テーブルの一覧表示: Athena データベース内のテーブルを一覧表示します。
Athena テーブルの説明: Athena テーブルの列名を取得します。
Athena のクエリ: マクロ置換、制限の適用、テンプレート変数サポート付きで、Grafana 経由で Amazon Athena に対して SQL クエリを実行します。

Snowflake クエリ

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

クエリは Grafana の Snowflake データソース（Grafana Enterprise プラグイン grafana-snowflake-datasource）を経由するため、認証は Grafana のデータソース設定によって処理されます。資格情報が MCP サーバーに表示されることはありません。これは ClickHouse ツールと同じモデルです。

Snowflake テーブルの一覧表示: INFORMATION_SCHEMA.TABLES 経由でテーブル（データベース、スキーマ、種類、行数、サイズを含む）を検出します。オプションのデータベース/スキーマフィルタがあります。
テーブルスキーマの説明: Snowflake テーブルの列名、データ型、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 Cloud でのみ動作します。有効にするには、agento11y を --enabled-tools フラグに追加してください。

会話の一覧表示と検索: 最近の LLM 会話を一覧表示するか、フィルター式（モデル、プロバイダー、エージェント、ステータス、エラータイプ、評価結果など）で時間範囲を指定して検索します。検索結果には、エラー数、評価サマリー、評価サマリー、トレース ID が含まれます。
会話の詳細の取得: 単一の会話を、そのすべての生成（プロンプトと出力を含む）とともに取得します。
生成の詳細とスコアの取得: ID で単一の生成を取得し、その評価スコア（評価者、スコアキー、値、合格、説明）を取得します。
エージェントカタログの読み取り: テレメトリを送信するエージェントを一覧表示し、1 つのエージェントバージョンを完全に取得し（完全なシステムプロンプト、JSON スキーマを持つすべてのツール、実行されたモデル）、エージェントのバージョン履歴を辿り、バージョンごとの評価スコア集計を比較します。有効なバージョンは sha256: ハッシュであり、ツールの変更が影響することはありません。独自のバージョンを報告しないエージェントの場合、システムプロンプトがハッシュされるため、プロンプトの編集で新しいバージョンが作成されます。カタログとバージョンの行には token_estimate が含まれており、完全なプロンプトを取得する前に確認する価値があります。
評価者とテンプレートの検査: スコアの由来となった評価者、それらが派生したテンプレート、LLM 判定評価者が利用できる判定プロバイダーとモデルを読み取ります。書き込みツールが有効な場合は、評価者の作成、フォーク、テスト、削除も行えます。
評価ルールとガードの検査: 評価者を本番トラフィックにバインドする非同期評価ルールと、インラインで実行され警告または拒否できるガード（フックルール）を読み取ります。書き込みツールが有効な場合は、それらの作成、更新、プレビュー、削除も行えます。書き込みと非永続的な preview_rule および test_evaluator 操作には、Agento11y Admin ロールによって付与される grafana-agento11y-app.eval:write 権限が必要です。
保存された会話とコレクションのキュレーション: 保存された会話（会話に安定した ID、名前、タグを付けるブックマーク）と、それらをグループ化するコレクション（各コレクションのメンバー数と、保存された会話の行に埋め込まれたコレクションを含む）を読み取ります。書き込みツールが有効な場合は、会話のブックマーク、コレクションの作成と編集、メンバーの追加または削除も行えます。これらの書き込みには同じ grafana-agento11y-app.eval:write 権限が必要です。
テストスイートの読み取りと編集: オフライン実験が実行されるバージョン付きテストスイートを一覧表示し、完全なバージョン履歴とともに 1 つを読み取り、バージョンのテストケースをページングします。書き込みツールが有効な場合は、スイートの作成、名前変更または再タグ付け、ドラフトバージョンのオープン、公開、テストケースの書き込みまたは削除も行えます。公開されたバージョンは固定されているため、編集は新しいドラフトを開くことを意味します。これらの書き込みには grafana-agento11y-app.eval:write が必要です。
オフライン実験の読み取り: テストスイートに対する評価実行を一覧表示し、主要な合格率、コスト、トークン合計とともに 1 つを読み取ります。テストケースごとのレポートからトライアル、各判定者の説明付きのスコア、アーティファクトメタデータまでドリルダウンします。書き込みツールが有効な場合は、実験の名前変更または再タグ付けと実行中の実験のキャンセルも行えます。これらには grafana-agento11y-app.eval:write が必要です。実験はこのツールではなく SDK ランナーによって作成されます。

Grafana アシスタント

注: アシスタントツールはデフォルトでは無効であり、対象の Grafana インスタンスに Grafana Assistant プラグイン (grafana-assistant-app) がインストールされている必要があります。また、これらは書き込みツールでもあります（アシスタントがスタックの状態を変更する可能性があります）。そのため、--disable-write が設定されている場合はスキップされます。有効にするには、assistant を --enabled-tools フラグに追加してください。

アシスタントに質問する: 自然言語のプロンプトを Grafana Assistant に送信し、完全なテキスト返信を待ちます。アシスタントは、単一のデータソースクエリを実行するよりも広範な、ツール、メトリクス、ログ、その他のスタックコンテキストを使用する場合があります。返された contextId をフォローアップ呼び出しで渡すと、同じ会話を継続できます。複雑なタスクは数分かかる場合があります。呼び出しは、返信が完了するか、リクエストがタイムアウトするまで（5 分間）ブロックされます。

インシデント

インシデントの検索、作成、更新: 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）
- 探索リンク: 事前設定されたデータソースを使用して 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 ロールを使用します:

ビューアーロール: 読み取り専用操作に必要です（インシデントの一覧表示、調査の取得）
エディターロール: 書き込み操作に必要です（インシデントの作成、調査の変更）

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_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*	テーブルスキーマを取得する（列タイプ、NULL許容性、デフォルト値、コメント）	`datasources:query`	`datasources:uid:*`
`query_snowflake`	Snowflake*	マクロ/変数置換を使用してSQLクエリを実行する	`datasources:query`	`datasources:uid:*`
`alerting_manage_rules`	Alerting	アラートルールを管理する（一覧表示、取得、バージョン、作成、更新、削除）	`alert.rules:read` + `alert.rules:write` 変更用	`folders:*` or `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	通知ポリシー、連絡先ポイント、時間間隔を管理する	`alert.notifications:read`	グローバルスコープ
`list_oncall_schedules`	OnCall	Grafana OnCallからスケジュールを一覧表示する	`grafana-oncall-app.schedules:read`	プラグイン固有のスコープ
`get_oncall_shift`	OnCall	特定のOnCallシフトの詳細を取得する	`grafana-oncall-app.schedules:read`	プラグイン固有のスコープ
`get_current_oncall_users`	OnCall	特定のスケジュールで現在オンコール中のユーザーを取得する	`grafana-oncall-app.schedules:read`	プラグイン固有のスコープ
`list_oncall_teams`	OnCall	Grafana OnCallからチームを一覧表示する	`grafana-oncall-app.user-settings:read`	プラグイン固有のスコープ
`list_oncall_users`	OnCall	Grafana OnCallからユーザーを一覧表示する	`grafana-oncall-app.user-settings:read`	プラグイン固有のスコープ
`list_alert_groups`	OnCall	フィルタリングオプションを使用してGrafana OnCallからアラートグループを一覧表示する	`grafana-oncall-app.alert-groups:read`	プラグイン固有のスコープ
`get_alert_group`	OnCall	IDでGrafana OnCallから特定のアラートグループを取得する	`grafana-oncall-app.alert-groups:read`	プラグイン固有のスコープ
`get_sift_investigation`	Sift	UUIDで既存のSift調査を取得する	ビューアーロール	該当なし
`get_sift_analysis`	Sift	Sift調査から特定の分析を取得する	ビューアーロール	該当なし
`list_sift_investigations`	Sift	オプションの制限付きでSift調査の一覧を取得する	ビューアーロール	該当なし
`find_error_pattern_logs`	Sift	Lokiログ内の高いエラーパターンを検出します。	エディターロール	該当なし
`find_slow_requests`	Sift	関連するTempoデータソースから遅いリクエストを検出します。	エディターロール	該当なし
`list_pyroscope_label_names`	Pyroscope	セレクタに一致するラベル名を一覧表示する	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	ラベル名のセレクタに一致するラベル値を一覧表示する	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	利用可能なプロファイルタイプを一覧表示する	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Pyroscopeからプロファイル、メトリクス、またはその両方をクエリする	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	指定されたエンティティのアサーションサマリーを取得する	プラグイン固有の権限	プラグイン固有のスコープ
`agento11y_manage_conversations`	Agent Observability*	Grafana Agent ObservabilityからLLM会話を一覧表示、検索、取得する	`grafana-agento11y-app.conversations:read`	該当なし
`agento11y_manage_generations`	Agent Observability*	Grafana Agent ObservabilityからLLM生成の詳細と評価スコアを取得する	`grafana-agento11y-app.data:read`	該当なし
`agento11y_manage_agents`	Agent Observability*	エージェントカタログを読み取る：エージェントの一覧表示、1つのエージェントバージョンの完全取得、バージョン履歴の一覧表示、バージョンごとのスコア集計	`grafana-agento11y-app.data:read`	該当なし
`agento11y_manage_evaluators`	Agent Observability*	評価者、評価者テンプレート、およびジャッジカタログを管理する（一覧表示、取得、アップサート、フォーク、テスト、削除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 変更とテスト用	該当なし
`agento11y_manage_eval_rules`	Agent Observability*	評価ルールとガードを管理する（一覧表示、取得、作成、更新、プレビュー、削除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 変更とプレビュー用	該当なし
`agento11y_manage_eval_collections`	Agent Observability*	保存された会話とそれらをグループ化するコレクションを管理する（一覧表示、取得、保存、作成、更新、削除、メンバーの追加と削除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 変更用	該当なし
`agento11y_manage_experiments`	Agent Observability*	オフライン実験、その試行、スコア、アーティファクトメタデータ、フィルターファセットを読み取る；実験を更新およびキャンセルする	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 変更用	該当なし
`agento11y_manage_test_suites`	Agent Observability*	オフライン実験が実行されるテストスイート、そのバージョン、およびテストケースを管理する（一覧表示、取得、作成、更新、ドラフト、公開、アップサート、削除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 変更用	該当なし
`ask_assistant`	Assistant*	Grafana Assistantにプロンプトを送信し、完全なテキスト応答を返す（マルチターン（`contextId`経由））	プラグイン固有の権限	プラグイン固有のスコープ
`generate_deeplink`	Navigation	Grafanaリソースの正確なディープリンクURLを生成する	なし（読み取り専用URL生成）	該当なし
`get_annotations`	Annotations	フィルタを使用してアノテーションを取得する	`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:*` または `dashboards:uid:abc123`
`get_snapshot`	スナップショット	スナップショットキーでスナップショットのメタデータとダッシュボードペイロードを取得	`dashboards:read`	`dashboards:*` または `dashboards:uid:abc123`
`create_snapshot`	スナップショット	完全なダッシュボードペイロードからダッシュボードスナップショットを作成	`dashboards:write`	`dashboards:*` または `dashboards:uid:abc123`
`delete_snapshot`	スナップショット	スナップショットキーでダッシュボードスナップショットを削除	`dashboards:write`	`dashboards:*` または `dashboards:uid:abc123`
`get_panel_image`	レンダリング	保存されたダッシュボードまたはパネル、あるいはリポジトリブランチからのプロビジョニングプレビューをPNG画像としてレンダリング	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	プロビジョニング	プロビジョニングリポジトリ（例：git-syncソース）を、ソースURL、ブランチ、同期状態、ヘルスとともに一覧表示	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	プロビジョニング	プロビジョニングリポジトリからファイルをドライラン適用し、アドミッション検証エラーを報告	`provisioning.repositories:read`	N/A
_* デフォルトでは無効です。有効にするには、`--enabled-tools` にカテゴリを追加してください。*

CLI フラグリファレンス

mcp-grafana バイナリは、設定のためのさまざまなコマンドラインフラグをサポートしています:

トランスポートオプション:

-t, --transport: トランスポートタイプ (stdio、sse、または streamable-http) - デフォルト: stdio
--address: SSE/streamable-http サーバーのホストとポート - デフォルト: localhost:8000
--base-path: SSE/streamable-http サーバーのベースパス
--endpoint-path: streamable-http サーバーのエンドポイントパス - デフォルト: /mcp
--server-name: MCP ハンドシェイクと OTel service.name で使用されるサーバー名 - デフォルト: mcp-grafana。GRAFANA_MCP_SERVER_NAME 環境変数を上書きします

HTTP トランスポートセキュリティ (SSE / streamable-http のみ):

Host/Origin 検証は、リスナー上のすべてのルート (/sse、/mcp、/healthz、/metrics) で強制されるため、DNS リバインディングブラウザはそのいずれにも到達できません。Stdio トランスポートは影響を受けません。

--allowed-hosts: Host ヘッダー値のカンマ区切り許可リスト。--address のループバックバリアント (例: localhost:8000,127.0.0.1:8000,[::1]:8000) がデフォルトです。空に解析される値 (未設定、,、, など) もデフォルトにフォールバックするため、タイプミスによってチェックが静かに無効化されることはありません。許可リスト外の Host ヘッダーを含むリクエストは 403 で拒否されます。* を渡すとチェックを無効化できます — これは、Host を書き換える信頼できるリバースプロキシの背後で実行する場合、または隔離されたネットワークでのみ安全です。K8s の httpGet プローブと外部の /metrics スクレイプでは、このリストに明示的なホスト名、*、または tcpSocket プローブ / 別のメトリクスポート (--metrics-address) が必要になります。
--allowed-origins: Origin ヘッダー値のカンマ区切り許可リスト。デフォルトでは空 — Origin ヘッダーを含むリクエストはすべて拒否されます (ブラウザはクロスオリジンリクエストに常にこれを送信し、ブラウザがこのサーバーを直接呼び出すべきではありません)。ブラウザベースのクライアントを許可するには明示的なリストを設定するか、チェックを無効化するには * を設定します。

呼び出し元認証 (SSE / streamable-http のみ):

オプションで、MCP クライアントがサーバーに対して認証を行うことを要求できます。これは、サーバーが Grafana に到達するために使用する認証情報とは別のものです。Stdio は影響を受けません。

--server-auth-token: 呼び出し元が Authorization: Bearer <token> として送信する必要があるベアラートークン。MCP_GRAFANA_SERVER_TOKEN 環境変数にフォールバックします。設定されている場合、有効なトークンがないリクエストは、ツールが実行される前に 401 で拒否されます。シークレットがプロセス引数に表示されないように、環境変数を使用することを推奨します。

呼び出し元認証は、--server-auth-token が設定されている場合にのみ強制されます。設定されておらず、サーバーが非ループバックアドレスにバインドされている場合、サーバーは起動しますが、セキュリティエラーをログに記録します — これは --log-level によって隠されないように error ログレベルで出力されます (ループバックと stdio は影響を受けません)。将来のメジャーリリースでは、これは起動エラーになります。非ループバックアドレスで呼び出し元認証を有効にする場合は、TLS (または TLS 終端) を使用してください。呼び出し元認証が有効な場合、検証済みの Authorization ヘッダーはリクエストが Grafana に到達する前に削除されます。--server-auth-token と GRAFANA_FORWARD_HEADERS=Authorization を組み合わせると、起動時に拒否されます。

デバッグとロギング:

--debug: 詳細な HTTP リクエスト/レスポンスロギングのためのデバッグモードを有効にします
--log-level: ログレベル (debug、info、warn、error) - デフォルト: info

Grafana クライアントオプション:

--grafana-timeout: Grafana クライアントが行うリクエストの時間制限。Go の期間文字列 (例: 10s、500ms) を受け入れます - デフォルト: 10s
--include-args-in-spans: OpenTelemetry スパンにツール呼び出し引数を含めます。本番環境以外、または引数に PII が含まれないことがわかっている場合にのみ有効にしてください - デフォルト: false

可観測性:

--metrics: /metrics で Prometheus メトリクスエンドポイントを有効にします
--metrics-address: メトリクスサーバー用の別のアドレス (例: :9090)。空の場合は、メインサーバーでメトリクスが提供されます
--slow-request-threshold: 任意の MCP リクエスト (ツール呼び出し、リスト、リソース読み取りなど) がこの期間より長くかかった場合にイベントをログに記録します。Go の期間文字列 (例: 500ms、5s) を受け入れます。デフォルトの 0 はスローリクエストロギングを無効にします。スローリクエストロギングセクションを参照してください。
--slow-request-log-level: スローリクエストイベントのログレベル (info または warn) - デフォルト: warn

セッション管理:

--session-idle-timeout-minutes: セッションのアイドルタイムアウト (分単位)。この期間アクティビティがないセッションは自動的に刈り取られます - デフォルト: 30。セッションの刈り取りを無効にするには 0 に設定します。SSE および streamable-http トランスポートにのみ関連します。

ツール設定:

--enabled-tools: 有効なカテゴリのカンマ区切りリスト - デフォルト: admin、agento11y、assistant、athena、clickhouse、cloudwatch、elasticsearch、examples、graphite、quickwit、runpanelquery、snowflake を除くすべてのカテゴリ。無効なカテゴリを有効にするには、リストに追加します (例: "search,datasource,...,snowflake")
--max-loki-log-limit: query_loki_logs 呼び出しあたりに返される最大ログ行数 - デフォルト: 100。注: 切り捨て検出を可能にするために、Loki のサーバー側の max_entries_limit_per_query より少なくとも 1 低く設定してください (ツールは内部で limit+1 を要求し、追加データが存在するかどうかを検出します)。
--disable-search: 検索ツールを無効にします
--disable-datasource: データソースツールを無効にします
--disable-incident: インシデントツールを無効にします
--disable-prometheus: Prometheus ツールを無効にします
--disable-write: 書き込みツール (作成/更新操作) を無効にします
--disable-loki: Loki ツールを無効にします
--disable-elasticsearch: Elasticsearch および OpenSearch ツールを無効にします
--disable-quickwit: Quickwit ツールを無効にします
--disable-influxdb: InfluxDB ツールを無効にします
--disable-alerting: アラートツールを無効にします
--disable-dashboard: ダッシュボードツールを無効にします
--disable-oncall: OnCall ツールを無効にします
--disable-asserts: Asserts ツールを無効にします
--disable-sift: Sift ツールを無効にします
--disable-admin: 管理ツールを無効にします
--disable-pyroscope: Pyroscope ツールを無効にします
--disable-navigation: ナビゲーションツールを無効にします
--disable-rendering: レンダリングツール (パネル/ダッシュボードの画像エクスポート) を無効にします
--disable-snapshot: スナップショットツールを無効にします
--disable-cloudwatch: CloudWatch ツールを無効にします
--disable-examples: クエリ例ツールを無効にします
--disable-clickhouse: ClickHouse ツールを無効にします
--disable-snowflake: Snowflake ツールを無効にします
--disable-runpanelquery: パネルクエリ実行ツールを無効にします
--disable-graphite: Graphite ツールを無効にします
--disable-athena: Athena ツールを無効にします
--disable-provisioning: プロビジョニングツールを無効にします
--disable-agento11y: Agent Observability ツールを無効にします
--disable-assistant: Grafana Assistant ツールを無効にします

読み取り専用モード

--disable-write フラグは、MCP サーバーを読み取り専用モードで実行する方法を提供し、Grafana インスタンスへの書き込み操作を防ぎます。これは、安全な読み取り専用アクセスを提供したいシナリオで役立ちます。例えば:

制限付きの読み取り専用権限を持つサービスアカウントを使用する
変更機能なしで AI アシスタントに可観測性データを提供する
書き込みアクセスを制限すべき本番環境で実行する
偶発的な変更を防ぎたいテストおよび開発シナリオ

--disable-write が有効な場合、次の書き込み操作が無効になります:

ダッシュボードツール:

update_dashboard

フォルダーツール:

create_folder

インシデントツール:

create_incident
add_activity_to_incident

アラートツール:

alerting_manage_rules (作成、更新、削除操作)

注釈ツール:

create_annotation
update_annotation

Sift ツール:

find_error_pattern_logs (調査を作成)
find_slow_requests (調査を作成)

スナップショットツール:

create_snapshot
delete_snapshot

Agent Observability ツール:

agento11y_manage_evaluators (upsert、削除、フォーク、テスト評価器の操作)
agento11y_manage_eval_rules (ルールとガードの作成、更新、削除、プレビュー操作)
agento11y_manage_eval_collections (保存済み会話の保存と削除; コレクションの作成、更新、削除; コレクションメンバーの追加と削除)
agento11y_manage_experiments (実験の更新とキャンセル操作)
agento11y_manage_test_suites (テストスイートの作成と更新; バージョンの作成と公開; テストケースの upsert と削除)

すべての読み取り操作は引き続き利用可能で、ダッシュボードのクエリ、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 をトークンを含むファイルパスに指定できます。ファイルはリクエストごとに新しく読み取られるため、サーバーを再起動しなくても、ローテーションされたトークンが自動的に取得されます。

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

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 環境変数を使用して、すべてのGrafana APIリクエストに任意のHTTPヘッダーを追加できます。値は、ヘッダー名を値にマッピングする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 でデフォルトを明示的に上書きし、標準入力を開いたままにするために -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
```
  注 — ネットワークモードの保護: SSEモードとstreamable-httpモードでは、コンテナは非ループバックアドレス（0.0.0.0:8000）にバインドします。呼び出し元トークンがない場合、サーバーは起動しますが、セキュリティエラーをログに記録します（error ログレベルで記録されるため、--log-level では非表示になりません。また、将来のメジャーリリースでは起動を拒否します）。クライアントからの Authorization: Bearer <token> を要求するには、MCP_GRAFANA_SERVER_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/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を使用していて、MCPサーバーをSSEモードで実行している場合（トランスポートを上書きせずに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>"
      }
    }
  }
}

注：標準設定と同様に、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)

URL検証：

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)

サーバーTLS設定（Streamable HTTPトランスポートのみ）

streamable HTTPトランスポート（-t streamable-http）を使用する場合、MCPサーバーをHTTPの代わりにHTTPSを提供するように設定できます。これは、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

これにより、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）またはstreamable HTTP（-t streamable-http）トランスポートを使用する場合、MCPサーバーは /healthz にヘルスチェックエンドポイントを公開します。このエンドポイントは、ロードバランサー、監視システム、またはオーケストレーションプラットフォームがサーバーが実行中で接続を受け入れていることを確認するために使用できます。

エンドポイント: GET /healthz

レスポンス：

ステータスコード: 200 OK
ボディ: ok

使用例：

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

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

注: ヘルスチェックエンドポイントは、SSEまたはstreamable HTTPトランスポートを使用する場合にのみ利用可能です。stdioトランスポート（-t stdio）では利用できません。stdioはHTTPサーバーを公開しないためです。

可観測性

MCPサーバーは、OTel MCPセマンティック規約に従って、Prometheusメトリクス、OpenTelemetry分散トレーシング、OpenTelemetryログエクスポートをサポートしています。トレーシングとログエクスポートは、標準の 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`	ヒストグラム	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またはstreamable HTTPトランスポートを使用する場合のみ利用可能です。stdioトランスポートでは利用できません。

遅延リクエストのログ記録

--slow-request-threshold フラグは、MCPリクエスト（ツール呼び出し、リスト、リソース読み取りなど）が指定された期間を超えるたびに、構造化ログイベントを出力します。完全なデバッグログに埋もれることなく、遅いクエリやツール呼び出しを診断するのに役立ちます。

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

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

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

ログイベントには、次の構造化属性が含まれます：

属性	説明
`mcp.method`	MCPメソッド（例：`tools/call`、`tools/list`、`resources/read`）
`duration`	観測されたリクエストの所要時間
`threshold`	設定されたしきい値
`tool`	ツール名（`tools/call` メソッドの場合のみ存在）
`error`	リクエストが失敗した場合のエラー値（ベストエフォートのコンテキスト。コンテンツは上流のエラーラッピングによって制御されます）
`error.type`	有界カーディナリティのエラー分類（型なしエラーの場合は `_OTHER`）

遅延リクエストのログ記録は、すべてのトランスポート（stdioを含む）で動作し、--metrics を必要としません。デフォルトのしきい値 0 は、これを完全に無効にします。プロキシされたツールは tools/call を通過し、自動的にカバーされます。

トレーシング

分散トレーシングは、標準の OTEL_* 環境変数を介して設定され、--metrics フラグとは独立して動作します。OTEL_EXPORTER_OTLP_ENDPOINT（またはシグナル固有の OTEL_EXPORTER_OTLP_TRACES_ENDPOINT）が設定されている場合、サーバーはOTLP/gRPCを介してトレースをエクスポートします：

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

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

ツール呼び出しスパンは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 を自動的に添付するため、ログレコードはサーバーがすでに出力しているトレースと関連付けられます。

トレースとログはエンドポイントを独立して解決するため、2つのシグナルを個別に有効にできます：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コレクターはオプションであり、ファンアウト、バッチ処理、複数バックエンドへのルーティングに役立ちますが、必須ではありません。

シグナル固有のバリアントである 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インスタンスと認証情報を設定する必要があります。

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

docker-compose up -d

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

make test-all

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

リンティング

コードをリントするには、次を実行します：

make lint

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

make lint-jsonschema

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

ライセンス

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