Grafana MCP server

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 などのインストール方法については、使用方法をご覧ください。

要件

• 全機能を利用するには、Grafana バージョン 9.0 以降が必要です。 API エンドポイントがないため、特にデータソース関連の操作など、一部の機能はそれ以前のバージョンでは正しく動作しない場合があります。

機能

MCP サーバーで現在利用できる機能は以下のとおりです。この一覧は参考情報であり、今後の機能のロードマップや提供を約束するものではありません。

ダッシュボード

• ダッシュボードの検索： タイトル、フォルダー UID、タグ、またはスター付きかどうかでダッシュボードを検索します
• UID でダッシュボードを取得： 固有の識別子を使って、ダッシュボードの詳細情報を取得します。省略可能な version を指定すると、現在のダッシュボードではなく保存済みのスナップショットを読み込みます。警告：大きなダッシュボードはコンテキストウィンドウを大量に消費する場合があります。
• ダッシュボードのバージョンを一覧表示： 保存済みのダッシュボードのバージョンを、バージョン番号、作成者、タイムスタンプ、保存メッセージなどのコンパクトなメタデータとして一覧表示します
• ダッシュボードの概要を取得： 完全な JSON を取得せずに、タイトル、パネル数、パネルの種類、変数、メタデータなどの概要を取得し、コンテキストウィンドウの使用量を最小限に抑えます
• ダッシュボードのプロパティを取得： JSONPath 式（例：$.title、$.panels[*].title）を使ってダッシュボードの特定の部分を抽出し、必要なデータのみを取得してコンテキストウィンドウの消費を抑えます
• ダッシュボードの更新または作成： 既存のダッシュボードを変更するか、新しいダッシュボードを作成します。警告：ダッシュボードの完全な JSON が必要なため、コンテキストウィンドウを大量に消費する場合があります。
• ダッシュボードのパッチ適用： 完全な JSON を必要とせずに、ダッシュボードに特定の変更を適用し、対象を絞った変更時のコンテキストウィンドウの使用量を大幅に抑えます
• パネルのクエリとデータソース情報を取得： ダッシュボード内の各パネルから、タイトル、クエリ文字列、データソース情報（利用可能な場合は UID と種類を含む）を取得します

パネルクエリの実行

注： パネルクエリ実行ツールは、デフォルトで無効になっています。有効にするには、--enabled-tools フラグに runpanelquery を追加してください。

• パネルクエリの実行： カスタムの時間範囲と変数の上書きを指定して、ダッシュボードパネルのクエリを実行します。Infinity パネルは、クエリで backend または jq-backend パーサーを使う場合に実行されます（Google Sheets クエリは常に該当します）。デフォルトの simple パーサーと UQL、GROQ パーサーはブラウザー内でのみ動作します。kniepdennis-neo4j-datasource プラグインの Neo4j パネルは、プラグインを通じて Cypher クエリを実行し、読み取り専用セッションを開きます。

コンテキストウィンドウの管理

ダッシュボードツールに、コンテキストウィンドウの使用量を効果的に管理するための複数の方法が追加されました（issue #101）。

• ダッシュボードの概要確認や変更の計画には get_dashboard_summary を使用してください
• ダッシュボードの特定の部分だけが必要な場合は、JSONPath とともに get_dashboard_property を使用してください
• ダッシュボードの完全な JSON が必要な場合を除き、get_dashboard_by_uid の使用は避けてください

データソース

• データソース情報の一覧表示と取得： 設定済みのすべてのデータソースを表示し、それぞれの詳細情報を取得します。
  • 対応するデータソースの種類：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch、OpenSearch、Snowflake、Athena。

クエリの例

注： クエリ例のツールは、デフォルトで無効になっています。有効にするには、--enabled-tools フラグに examples を追加してください。

• クエリの例を取得： さまざまなデータソースの種類に対応するクエリ例を取得し、クエリ構文を学べます。

Prometheus のクエリ

• Prometheus にクエリを実行： Prometheus データソースに対して、PromQL クエリを実行します（瞬時クエリと範囲指定のメトリクスクエリの両方に対応しています）。
• Prometheus のメタデータをクエリ： Prometheus データソースから、メトリクスのメタデータ、メトリクス名、ラベル名、ラベル値を取得します。
• ヒストグラムのパーセンタイルをクエリ： histogram_quantile を使用して、ヒストグラムのパーセンタイル値（p50、p90、p95、p99）を計算します。

Loki のクエリ

• Loki のログとメトリクスをクエリ： LogQL を使用して、Loki に対するログクエリとメトリクスクエリの両方を実行します。
• Loki のメタデータをクエリ： Loki からラベル名、ラベル値、ストリーム統計を取得します。
• Loki のパターンをクエリ： Loki が検出したログパターンを取得し、一般的なログ構造や異常を特定します。

InfluxDB のクエリ

注： InfluxDB ツールは、デフォルトで無効になっています。有効にするには、--enabled-tools フラグに influxdb を追加してください。

• InfluxDB にクエリを実行： InfluxQL（v1.x）または Flux（v2.x）を使用して、InfluxDB データソースに対するクエリを実行します。クエリ言語はデータソースの設定から推測されますが、dialect パラメーターで明示的に指定することもできます。

SQL データソースのクエリ

注： SQL ツールは、デフォルトで無効になっています。有効にするには、--enabled-tools フラグに sql を追加してください。後方互換性のため、clickhouse、snowflake、athena のエイリアスも使用できます。

統合 SQL ツールでは、単一のツールセットを通じてClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQLに対応しています。クエリは Grafana のデータソースプラグインを経由するため、認証はデータソースの設定によって処理され、認証情報が MCP サーバーに渡されることはありません。

• データベース／スキーマ／カタログを一覧表示： SQL データソースの組織単位を確認します。Athena では、カタログを省略するとカタログが一覧表示され、カタログを渡すとデータベースが一覧表示されます。
• テーブルを一覧表示： データベースまたはスキーマ内のテーブルを、メタデータ（行数や、利用可能な場合はサイズ）とともに一覧表示します。
• テーブルスキーマを確認： 列名、型、NULL 許容性、デフォルト値、コメントを取得します。
• SQL クエリを実行： データソース固有のマクロ置換（$__timeFilter(col)、$__from/$__to、$__interval、${varname}）、自動的な上限適用、テンプレート変数のサポートにより、SQL クエリを実行します。

CloudWatch のクエリ

注： CloudWatch ツールは、デフォルトで無効になっています。有効にするには、--enabled-tools フラグに cloudwatch を追加してください。

• CloudWatch の名前空間を一覧表示： 利用可能な AWS CloudWatch の名前空間を確認します。
• CloudWatch のメトリクスを一覧表示： 指定した名前空間で利用可能なメトリクスを一覧表示します。
• CloudWatch のディメンションを一覧表示： メトリクスクエリのフィルタリングに使用するディメンションを取得します。
• CloudWatch にクエリを実行： 時間範囲を指定して、CloudWatch のメトリクスクエリを実行します。
• CloudWatch のロググループを一覧表示： ロググループを確認します。名前のプレフィックスで絞り込むこともできます。
• CloudWatch のロググループのフィールドを一覧表示： ロググループで利用可能なフィールドを確認します。
• CloudWatch Logs にクエリを実行： 1 つ以上のロググループを対象に、CloudWatch Logs Insights のクエリを実行します。

Google Cloud Logging のクエリ

Note: Google Cloud Logging ツールはデフォルトで無効になっています。有効にするには、--enabled-tools フラグに cloudlogging を追加してください。Google Cloud Logging データソースプラグイン（googlecloud-logging-datasource）のバージョン 1.8.0 以降が必要です。また、Grafana 11.2 以降が必要です。古いバージョンのプラグインでは異なるレスポンス形式が返され、query_cloud_logging はアップグレードを求めるエラーを報告します。

• Cloud Logging プロジェクトの一覧表示： データソースがログを読み取れる GCP プロジェクト ID を検出します。
• Cloud Logging バケットとビューの一覧表示： クエリの対象を絞り込むために、ログバケットとログビューを検出します。
• Cloud Logging のクエリ： Cloud Logging のクエリ言語のフィルター（例：resource.type="k8s_container" AND severity>=ERROR）を時間範囲と上限を指定して実行します。重大度、本文、ラベル、トレース ID を含むエントリが新しい順に返されます。GCP の認証はデータソースの設定によって処理されます。

Graphite のクエリ

Note: Graphite ツールはデフォルトで無効になっています。有効にするには、--enabled-tools フラグに graphite を追加してください。

• Graphite のクエリ： Graphite データソースに対して Graphite Render API クエリを実行します。
• Graphite メトリクスの一覧表示： Graphite のメトリクスパスを参照し、検出します。
• Graphite タグの一覧表示： 利用可能な Graphite のタグとタグ値を一覧表示します。
• Graphite 密度のクエリ： 指定したパターンに一致する Graphite メトリクスの密度をクエリします。

Elasticsearch/OpenSearch のクエリ

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

• Elasticsearch/OpenSearch のクエリ： Lucene クエリ構文または Elasticsearch Query DSL を使用して、Elasticsearch または OpenSearch のデータソースに対して検索クエリを実行します。時間範囲によるフィルタリングと、ログ、メトリクス、またはインデックス化された任意のデータの取得に対応しています。インデックス、ID、ソースフィールド、任意の関連度スコアを含むドキュメントが返されます。

Quickwit のクエリ

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

• Quickwit のクエリ： Lucene クエリ構文または Elasticsearch Query DSL の一部と互換性のある構文を使用して、Quickwit データソースに対して検索クエリを実行します。時間範囲によるフィルタリングと、ログまたはその他のインデックス化されたドキュメントの取得に対応しています。インデックス、ID、ソースフィールド、任意の関連度スコアを含むドキュメントが返されます。

エージェントの可観測性

Note: エージェントの可観測性ツールはデフォルトで無効になっており、Grafana Cloud でのみ動作します。有効にするには、--enabled-tools フラグに agento11y を追加してください。

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

Grafana アシスタント

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

• アシスタントに質問する： Grafana Assistant に自然言語のプロンプトを送信し、全文の返信を待ちます。アシスタントはツール、メトリクス、ログなどのスタックのコンテキストを利用できます。これは、単一のデータソースクエリを実行するよりも幅広い機能です。会話を続けるには、後続の呼び出しで返された contextId を渡してください。複雑なタスクには数分かかる場合があります。返信が完了するか、リクエストがタイムアウト（5 分）するまで、呼び出しはブロックされます。

インシデント

• インシデントの検索、作成、更新： Grafana Incident のインシデントを管理します。検索、作成、アクティビティの追加、カスタムフィールドの読み取りや設定を行えます。

アラート

• アラートルールの情報を一覧表示、取得： Grafana のアラートルールとそのステータス（発火中／正常／エラーなど）を表示します。Grafana 管理のルールと、Prometheus または Loki のデータソースで管理されるルールの両方をサポートします。
• アラートルールの作成、更新： 新しいアラートルールを作成するか、既存のルールを変更します。
• アラートルールの削除： UID を指定してアラートルールを削除します。
• アラートルーティングの管理： 通知ポリシー、コンタクトポイント、時間間隔を表示します。Grafana 管理のコンタクトポイントと、外部の Alertmanager データソース（Prometheus Alertmanager、Mimir、Cortex）のレシーバーの両方をサポートします。

Grafana OnCall

• スケジュールの一覧表示、管理： Grafana OnCall のオンコールスケジュールを表示、管理します。
• シフトの詳細を取得： 特定のオンコールシフトの詳細情報を取得します。
• 現在オンコール中のユーザーを取得： スケジュールで現在オンコール中のユーザーを確認します。
• チームとユーザーの一覧表示： すべての OnCall チームとユーザーを表示します。
• アラートグループの一覧表示： 状態、インテグレーション、ラベル、時間範囲などの条件で Grafana OnCall のアラートグループを表示、絞り込みます。
• アラートグループの詳細を取得： ID を指定して、特定のアラートグループの詳細情報を取得します。

管理

注記： 管理ツールはデフォルトで無効になっています。有効にするには、--enabled-tools フラグに admin を追加してください。

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

ユーザー

• ユーザー情報： 現在の Grafana の ID（ログイン名、メールアドレス、名前、Grafana（サーバー）管理者かどうか、現在の組織、認証情報でアクセスできる組織とそのロール）を取得します。複数組織のリクエストで有効な orgId 値を確認する際に使用してください。

ナビゲーション

• ディープリンクの生成： 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?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}）。Grafana 10.2 未満では panes が認識されないため、代わりに従来の ?left={...} 形式が出力されます。
  • 時間範囲のサポート： リンクに時間範囲パラメーターを追加します（from=now-1h&to=now）
  • カスタムパラメーター： ダッシュボード変数や更新間隔などの追加のクエリパラメーターを含めます

アノテーション

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

スナップショット

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

レンダリング

• パネルまたはダッシュボード画像の取得： Grafana のダッシュボードパネルまたはダッシュボード全体を PNG 画像としてレンダリングします。レポート、アラート、プレゼンテーションで使用できるよう、画像を Base64 エンコードしたデータとして返します。デフォルトのサイズは、パネルの場合は CSS ピクセルで 1000×750、ダッシュボード全体の場合は 1200×900 で、どちらもスケールは 1 です。Explore のデフォルトはスケール 1 で 1000×1000 です。寸法は画像レンダラーのビューポート制限の影響を受けます。寸法、時間範囲、テーマ、スケール、ダッシュボード変数をカスタマイズできます。また、オプションの 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 サーバー操作を可能にします。手動で適用するスコープよりも粒度が粗く（したがって制限が緩い）ため、厳密な最小権限アクセスよりも利便性を優先する場合にのみ使用してください。

注: OnCall やその他のプラグインベースのツールは、grafana-irm-app.schedules:read などのプラグインアクションによって認可されます。基本的な Viewer ロールには読み取りアクションが、Editor には書き込みアクションが含まれます。インシデントツールには plugins.app:access のみが必要です。IRM はインシデントアクションを基本ロールによって認可します。

dashboard.grafana.app/dashboards:get のような group/resource:verb 形式のアクションは、on-behalf-of アクセストークンにのみ適用されます。サービスアカウントには、リストされている他のアクションのみが必要です。

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:* or teams:id:1
list_users_by_org	管理*	検索とページネーションを使用して、組織内のユーザーを一覧表示します	org.users:read	global.users:* or global.users:id:123
list_all_roles	管理*	すべての Grafana ロールを一覧表示します	roles:read	roles:*
get_role_details	管理*	Grafana ロールの詳細を取得します	roles:read	roles:uid:editor
get_role_assignments	管理*	ロールの割り当てを一覧表示します	roles:read, teams.roles:read, users.roles:read	roles:uid:editor
list_user_roles	管理*	ユーザーのロールを一覧表示します	users.roles:read	global.users:id:123
list_team_roles	管理*	チームのロールを一覧表示します	teams.roles:read	teams:id:7
get_resource_permissions	管理*	リソースの権限を一覧表示します	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:uid:abcd1234
get_resource_description	管理*	Grafana リソースタイプの説明を取得します	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:*
user_info	ユーザー	現在の ID、機能、アクセス可能な組織	なし	—
search_dashboards	検索	クエリ、フォルダー UID、タグ、またはスター付きでダッシュボードを検索します	dashboards:read, folders:read	dashboards:* or dashboards:uid:abc123
search_folders	検索	タイトルでフォルダーを検索します	folders:read	folders:* or folders:uid:xyz789
get_dashboard_by_uid	ダッシュボード	UID でダッシュボードを取得します。保存済みのバージョンを指定することもできます	dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:write	dashboards:uid:abc123
list_dashboard_versions	ダッシュボード	ダッシュボードの保存済みバージョンを一覧表示します（バージョン、作成者、時刻、メッセージ）	dashboards:read, dashboards:write	dashboards:uid:abc123
update_dashboard	ダッシュボード	ダッシュボードを更新または新規作成します	dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:read	dashboards:*, folders:* or folders:uid:xyz789
get_dashboard_panel_queries	ダッシュボード	ダッシュボードからパネルのタイトル、クエリ、データソース UID、タイプを取得します	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
run_panel_query	RunPanelQuery*	1 つ以上のダッシュボードパネルクエリを実行します	dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:read	dashboards:uid:*, datasources:uid:*
get_dashboard_property	ダッシュボード	JSONPath 式を使用してダッシュボードの特定の部分を抽出します	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
get_dashboard_summary	ダッシュボード	JSON 全体を取得せずに、ダッシュボードの簡潔な概要を取得します	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
create_folder	ダッシュボード	フォルダーを作成します	folders:create, folders:read, folders:write	folders:*
list_datasources	データソース	データソースを一覧表示します	datasources:read	datasources:*
get_datasource	データソース	UID または名前でデータソースを取得します	datasources:read	datasources:uid:prometheus-uid
check_datasources_health	データソース	1 つ以上のデータソースの健全性を確認します	datasources:query, datasources:read	datasources:uid:*
create_datasource	データソース	データソースを作成します	datasources:create, datasources:read	datasources:*
update_datasource	データソース	データソースを更新します	datasources:read, datasources:write	datasources:* or datasources:uid:abc123
get_query_examples	サンプル*	データソースタイプのクエリ例を取得します	なし	datasources:*
query_prometheus	Prometheus	Prometheus データソースに対してクエリを実行します	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_metadata	Prometheus	メトリクスのメタデータを一覧表示します	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	利用可能なメトリクス名を一覧表示します	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	セレクターに一致するラベル名を一覧表示します	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	特定のラベルの値を一覧表示します	datasources:query, datasources:read	datasources:uid:prometheus-uid
query_prometheus_histogram	Prometheus	ヒストグラムのパーセンタイル値を計算します	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_incidents	インシデント	Grafana Incident のインシデントを一覧表示します。カスタムフィールドの値も指定できます	plugins.app:access	N/A
create_incident	インシデント	Grafana Incident でインシデントを作成します。カスタムフィールドも設定できます	plugins.app:access	N/A
add_activity_to_incident	インシデント	Grafana Incident のインシデントにアクティビティ項目を追加します	plugins.app:access	N/A
update_incident	インシデント	Grafana Incident のインシデントを更新します（ステータス、重大度、タイトル、カスタムフィールド）	plugins.app:access	N/A
get_incident	インシデント	ID で単一のインシデントを取得します。カスタムフィールドも含まれます	plugins.app:access	N/A
list_incident_custom_fields	インシデント	インシデント用に設定されたカスタムフィールドを、タイプと選択肢とともに一覧表示します	plugins.app:access	N/A
query_loki_logs	Loki	LogQL を使用してログをクエリし、取得します（ログクエリまたはメトリクスクエリ）	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_names	Loki	ログ内で利用可能なすべてのラベル名を一覧表示します	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_values	Loki	特定のログラベルの値を一覧表示します	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_stats	Loki	ログストリームに関する統計情報を取得します	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_patterns	Loki	検出されたログパターンをクエリして、共通する構造を特定します	datasources:query, datasources:read	datasources:uid:loki-uid
analyze_loki_labels	Loki	Loki のラベル戦略を監査し（ライブまたは静的）、必要に応じてクエリのパフォーマンスを診断します	datasources:query, datasources:read	datasources:uid:loki-uid
suggest_loki_alloy_label_config	設定	承認済みラベルを強制する Alloy loki.process スニペットを生成します	なし	N/A
query_influxdb	InfluxDB*	InfluxQL（v1）または Flux（v2）を使用して InfluxDB にクエリを実行します	datasources:query, datasources:read	datasources:uid:influxdb-uid
list_sql_databases	SQL*	SQL データソースのデータベース、スキーマ、またはカタログを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_sql_tables	SQL*	SQL データソースのテーブルを一覧表示します	datasources:query, datasources:read	datasources:uid:*
describe_sql_table	SQL*	テーブルの列スキーマを取得します	datasources:query, datasources:read	datasources:uid:*
query_sql	SQL*	マクロ置換を使用して SQL クエリを実行します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_namespaces	CloudWatch*	利用可能な AWS CloudWatch 名前空間を一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_metrics	CloudWatch*	名前空間内のメトリクスを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimensions	CloudWatch*	メトリクスのディメンションを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimension_values	CloudWatch*	ディメンションキーの値を一覧表示します	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch	CloudWatch*	CloudWatch メトリクスクエリを実行します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_groups	CloudWatch*	CloudWatch ロググループを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_group_fields	CloudWatch*	ロググループ内で検出されたフィールドを一覧表示します	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch_logs	CloudWatch*	CloudWatch Logs Insights クエリを実行します	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_projects	Cloud Logging*	Google Cloud Logging データソースから読み取り可能な GCP プロジェクトを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_buckets	Cloud Logging*	GCP プロジェクト内のログバケットを一覧表示します	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_views	Cloud Logging*	ログバケット内のログビューを一覧表示します	datasources:query, datasources:read	datasources:uid:*
query_cloud_logging	Cloud Logging*	Cloud Logging クエリ言語でログをクエリします	datasources:query, datasources:read	datasources:uid:*
query_elasticsearch	Elasticsearch/OpenSearch*	Lucene 構文または Query DSL を使用して Elasticsearch または OpenSearch にクエリを実行します	datasources:query, datasources:read	datasources:uid:datasource-uid
query_quickwit	Quickwit*	Lucene 構文または Query DSL を使用して Quickwit にクエリを実行します	datasources:query, datasources:read	datasources:uid:quickwit-uid
alerting_rules_read	アラート	アラートルールを一覧表示して確認します（一覧表示、取得、バージョン）	alert.rules.external:read, alert.rules:read, datasources:read, folders:read	folders:* or folders:uid:alerts-folder
alerting_rules_write	アラート	Grafana 管理ルールを作成、更新、削除するか、データソース管理ルールを明示的に作成します	alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:read	folders:*, or datasources:uid:<uid> for external creation
alerting_manage_routing	アラート	通知ポリシー、コンタクトポイント、時間間隔を管理します	alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get	グローバルスコープ
alerting_routing_write	アラート	デフォルトで Grafana 管理のコンタクトポイントを作成するか、外部 Alertmanager レシーバーを明示的に作成します	alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read	グローバル、または外部作成の場合は datasources:uid:<uid>
alerting_silences_read	アラート	アラートのサイレンスを一覧表示して確認します（一覧表示、取得）	alert.instances:read, alert.silences:read	グローバルスコープ
alerting_silences_write	アラート	アラートのサイレンスを作成、更新、期限切れにします	alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write	グローバルスコープ
list_oncall_schedules	OnCall	Grafana OnCall のスケジュールを一覧表示します	grafana-irm-app.schedules:read, plugins.app:access	プラグイン固有のスコープ
get_oncall_shift	OnCall	特定の OnCall シフトの詳細を取得します	grafana-irm-app.schedules:read, plugins.app:access	プラグイン固有のスコープ
get_current_oncall_users	OnCall	特定のスケジュールで現在オンコール中のユーザーを取得します	grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access	プラグイン固有のスコープ
list_oncall_teams	OnCall	Grafana OnCall のチームを一覧表示します	grafana-irm-app.user-settings:read, plugins.app:access	プラグイン固有のスコープ
list_oncall_users	OnCall	Grafana OnCall のユーザーを一覧表示します	grafana-irm-app.user-settings:read, plugins.app:access	プラグイン固有のスコープ
list_alert_groups	OnCall	フィルタリングオプションを使用して、Grafana OnCall のアラートグループを一覧表示します	grafana-irm-app.alert-groups:read, plugins.app:access	プラグイン固有のスコープ
get_alert_group	OnCall	ID で Grafana OnCall の特定のアラートグループを取得します	grafana-irm-app.alert-groups:read, plugins.app:access	プラグイン固有のスコープ
update_alert_group	OnCall	アラートグループを確認、確認解除、解決、または解決解除します	grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access	プラグイン固有のスコープ
list_pyroscope_label_names	Pyroscope	セレクターに一致するラベル名を一覧表示します	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_label_values	Pyroscope	ラベル名のセレクターに一致するラベル値を一覧表示します	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	利用可能なプロファイルタイプを一覧表示します	datasources:query, datasources:read	datasources:uid:pyroscope-uid
query_pyroscope	Pyroscope	Pyroscope からプロファイル、メトリクス、またはその両方をクエリします	datasources:query, datasources:read	datasources:uid:pyroscope-uid
get_assertions	アサーション	指定したエンティティのアサーション概要を取得します	plugins.app:access	プラグイン固有のスコープ
agento11y_manage_conversations	エージェントオブザーバビリティ*	Grafana Agent Observability から LLM の会話を一覧表示、検索、取得します	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_generations	エージェントオブザーバビリティ*	Grafana Agent Observability から LLM 生成の詳細と評価スコアを取得します	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_agents	エージェントオブザーバビリティ*	エージェントカタログを読み取ります：エージェントの一覧表示、1 つのエージェントのバージョン全体の取得、バージョン履歴の一覧表示、バージョンごとのスコア集計の取得	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_evaluators	エージェントオブザーバビリティ*	評価器、評価器テンプレート、ジャッジカタログを管理します（一覧表示、取得、アップサート、フォーク、テスト、削除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 書き込みを有効にした場合は grafana-agento11y-app.eval:write も必要です	N/A
agento11y_manage_eval_rules	エージェントオブザーバビリティ*	評価ルールとガードを管理します（一覧表示、取得、作成、更新、プレビュー、削除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 書き込みを有効にした場合は grafana-agento11y-app.eval:write も必要です	N/A
agento11y_manage_eval_collections	エージェントオブザーバビリティ*	保存済みの会話と、それらをまとめるコレクションを管理します（一覧表示、取得、保存、作成、更新、削除、メンバーの追加と削除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 書き込みを有効にした場合は grafana-agento11y-app.eval:write も必要です	N/A
agento11y_manage_experiments	エージェントオブザーバビリティ*	オフライン実験、その試行、スコア、アーティファクトのメタデータ、フィルターファセットを読み取り、実験を更新およびキャンセルします	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 書き込みを有効にした場合は grafana-agento11y-app.eval:write も必要です	N/A
agento11y_manage_test_suites	エージェントオブザーバビリティ*	オフライン実験で使用するテストスイート、そのバージョン、テストケースを管理します（一覧表示、取得、作成、更新、下書き、公開、アップサート、削除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 書き込みを有効にした場合は grafana-agento11y-app.eval:write も必要です	N/A
ask_assistant	アシスタント*	Grafana Assistant にプロンプトを送信し、返信全文を返します（contextId を介した複数ターンに対応）	grafana-assistant-app.chats:access, plugins.app:access	プラグイン固有のスコープ
generate_deeplink	ナビゲーション	Grafana リソースへの正確なディープリンク URL を生成します	なし	N/A
get_annotations	注釈	フィルターを指定して注釈を取得します	annotations:read	annotations:* or annotations:id:123
create_annotation	注釈	新しい注釈を作成します（標準形式または Graphite 形式）	annotations:create	annotations:*
update_annotation	注釈	注釈の特定のフィールドを更新します（部分更新）	annotations:read, annotations:write	annotations:*
delete_annotation	注釈	ID で注釈を削除します	annotations:delete	annotations:*
get_annotation_tags	注釈	必要に応じてフィルターを指定して注釈タグを一覧表示します	annotations:read	annotations:*
list_snapshots	スナップショット	必要に応じてクエリと上限のフィルターを指定してダッシュボードスナップショットを一覧表示します	snapshots:read	N/A
get_snapshot	スナップショット	スナップショットキーでスナップショットのメタデータとダッシュボードのペイロードを取得します	なし	N/A
create_snapshot	スナップショット	ダッシュボードの完全なペイロードからダッシュボードスナップショットを作成します	dashboards:read, snapshots:create	dashboards:uid:abc123
delete_snapshot	スナップショット	スナップショットキーでダッシュボードスナップショットを削除します	dashboards:write, snapshots:delete	dashboards:uid:abc123
get_panel_image	レンダリング	保存済みのダッシュボードまたはパネル、プロビジョニングのプレビュー、またはアドホックな Explore ビューを PNG 画像としてレンダリングします	dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:read	dashboards:uid:abc123
list_provisioning_repositories	プロビジョニング	ソース URL、ブランチ、同期状態、健全性とともにプロビジョニングリポジトリ（例：git-sync ソース）を一覧表示します	provisioning.grafana.app/repositories:list, provisioning.repositories:read	N/A
validate_provisioning_file	プロビジョニング	プロビジョニングリポジトリのファイルをドライラン適用し、アドミッション検証エラーを報告します	dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:read	N/A
search_docs	ドキュメント	Grafana ドキュメントを検索するか、製品グループを一覧表示します（製品を一覧表示するにはクエリを省略します）	なし	N/A
get_doc	ドキュメント	ドキュメントページを取得します。見出しを取得するには outline_only を、範囲を指定して取得するには section を設定します	なし	N/A
search_tempo_traces	Tempo	TraceQL でトレースを検索します	datasources:query, datasources:read	datasources:uid:tempo-uid
query_tempo_metrics	Tempo	TraceQL でトレースからメトリクスを計算します	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_trace	Tempo	ID でトレースを取得します	datasources:query, datasources:read	datasources:uid:tempo-uid
diff_tempo_traces	Tempo	2 つのトレースを比較します	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_names	Tempo	スパン属性名とリソース属性名を一覧表示します	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_values	Tempo	トレース属性の値を一覧表示します	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_traceql_docs	Tempo	TraceQL のドキュメントを取得します	なし	N/A
query_graphite	Graphite*	Graphite メトリクスにクエリを実行します	datasources:query, datasources:read	datasources:uid:graphite-uid
query_graphite_density	Graphite*	Graphite メトリクス密度にクエリを実行します	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_metrics	Graphite*	Graphite メトリクスを一覧表示します	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_tags	Graphite*	Graphite タグを一覧表示します	datasources:query, datasources:read	datasources:uid:graphite-uid
get_plugin	プラグイン	インストール済みプラグインを取得します	plugins.app:access	N/A
search_plugin_information	プラグイン	grafana.com のプラグインカタログを検索します	なし	N/A
install_plugin	プラグイン	プラグインをインストールします	plugins:install	N/A
grafana_api_request	API	Grafana HTTP API エンドポイントを呼び出します	なし	エンドポイントによって異なります
* デフォルトでは無効です。有効にするには、カテゴリを --enabled-tools に追加してください。

Tempo クエリツールが有効な場合、互換性のある MCP ホストでは get_tempo_trace ツールによってインタラクティブなトレースビューアーが表示されます。従来のテキスト出力も引き続き利用できます。セットアップとライブラリへの埋め込みについては、MCP Apps をご覧ください。

CLI フラグのリファレンス

mcp-grafana バイナリでは、設定用にさまざまなコマンドラインフラグをサポートしています。

トランスポートのオプション：

• -t, --transport：トランスポートの種類（stdio、sse、または streamable-http） - デフォルト：stdio
• --address：SSE/streamable-http サーバーのホストとポート - デフォルト：localhost:8000
• --base-path：SSE/streamable-http サーバーのベースパス。/healthz と /metrics はこのプレフィックスの下ではなく、常にサーバーのルートで提供されます。これらはプローブとスクレイパー専用の内部エンドポイントです。アプリケーションのプレフィックスの外に置くことで、それらも公開せずにリバースプロキシ経由で API を公開しやすくなります。
• --endpoint-path：streamable-http サーバーのエンドポイントパス。--base-path の末尾に追加されます - デフォルト：/mcp
• --sse-keepalive：各 SSE クライアントに送信する ping リクエストの間隔です。リバースプロキシやロードバランサーがアイドル状態のイベントストリームを閉じて（セッションが終了して）しまうのを防ぎます。プロキシのアイドルタイムアウトより短い値に設定してください。たとえば、ingress-nginx のデフォルトの 60s の proxy-read-timeout の背後では 30s に設定します。ping が連続して 3 回、各間隔の半分の時間内に応答されなかった場合、クライアントは切断されます。Go の duration 文字列を受け付け、最小値は 1s です - デフォルト：0（無効）。--transport sse の場合にのみ適用されます。
• --server-name：MCP ハンドシェイクおよび OTel の service.name で使用するサーバー名 - デフォルト：mcp-grafana。環境変数 GRAFANA_MCP_SERVER_NAME の値を上書きします。
• --instructions-append：初期化時に MCP クライアントへ返すサーバーの指示に追加するテキストです。これにより、接続するすべてのエージェントにその内容が表示されます。

メモ

SSE 経由では、リクエストごとのヘッダーはツール呼び出しに届きません。X-Grafana-Service-Account-Token / X-Grafana-API-Key、X-Grafana-Org-Id、および GRAFANA_FORWARD_HEADERS に記載されたヘッダーは効果がなく、ツール呼び出しではサーバーの環境認証情報が使用されます。また、X-Grafana-URL による上書きも機能しません。呼び出し元ごとに異なる Grafana URL、認証情報、または組織が必要な場合は、streamable-http を使用してください。

HTTP トランスポートのセキュリティ（SSE / streamable-http のみ）：

Host / Origin の検証は、MCP リスナー上のすべてのルート（/sse、/mcp、および同じリスナーを共有する場合の /healthz / /metrics）で適用されます。そのため、DNS リバインディングを使うブラウザーからこれらのいずれにもアクセスできません。stdio トランスポートには影響しません。--healthz-address と --metrics-address は、ラップされていない別のリスナーを起動します。

• --allowed-hosts：Host ヘッダー値のカンマ区切りの許可リストです。デフォルトでは、--address のループバックアドレスの各形式が設定されます（例：localhost:8000,127.0.0.1:8000,[::1]:8000）。空として解析される値（未設定、,、, など）もデフォルトにフォールバックするため、入力ミスでチェックがひそかに無効になることはありません。許可リストにない Host ヘッダーを含むリクエストは 403 で拒否されます。* を指定すると Host の検証が無効になります。ただし、信頼できるリバースプロキシが Host を検証する場合に限り安全です。K8s の httpGet プローブと外部からの /metrics スクレイプには、このリストへの明示的なホスト名の指定、*、tcpSocket プローブ、または別ポート（--healthz-address／--metrics-address）のいずれかが必要です。
• --allowed-origins：Origin ヘッダー値のカンマ区切りの許可リストです。デフォルトは空です。Origin ヘッダーを含むリクエストはすべて拒否されます（ブラウザーはクロスオリジンリクエストで常にこのヘッダーを送信します。また、ブラウザーからこのサーバーを直接呼び出すべきではありません）。ブラウザーベースのクライアントを許可するには、明示的なリストを設定するか、チェックを無効にするには * を指定します。
• --allow-grafana-url-override：X-Grafana-URL による選択を有効にします。GRAFANA_ALLOW_URL_OVERRIDE にフォールバックします。デフォルトでは無効です。許可リストがない場合、呼び出し元はサーバーから到達可能な任意の HTTP(S) URL を選択できます。
• --allowed-grafana-urls：URL オーバーライド用の、Grafana ベース URL の完全一致を指定する任意のカンマ区切り許可リストです。GRAFANA_ALLOWED_URLS にフォールバックします。--allow-grafana-url-override が必要です。明示的に空のフラグを指定すると、継承したリストが無効になります。

呼び出し元の認証（SSE／streamable-http のみ）：

任意で、MCP クライアントにサーバーへの認証を要求できます。これは、サーバーが Grafana に接続する際に使用する認証情報とは別のものです。stdio には影響しません。

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

呼び出し元の認証は、--server-auth-token が設定されている場合にのみ適用されます。設定されていない状態でサーバーがループバック以外のアドレスにバインドされると、サーバーは起動しますが、セキュリティエラーをログに記録します。このログは error ログレベルで出力されるため、--log-level で隠されません（ループバックと stdio には影響しません）。将来のメジャーリリースでは、起動エラーになります。ループバック以外のアドレスで呼び出し元の認証を有効にする場合は、TLS（または TLS 終端）を使用してください。呼び出し元の認証が有効な場合、検証済みの Authorization ヘッダーは Grafana にリクエストが届く前に削除されます。また、--server-auth-token と GRAFANA_FORWARD_HEADERS=Authorization の併用は起動時に拒否されます。

Grafana URL のオーバーライド（streamable-http のみ）：

警告

URL オーバーライドを使うと、MCP の呼び出し元が送信先の HTTP(S) を選択できます。許可リストで URL を制限できますが、呼び出し元の認証や、トークンと送信先の紐付けは行われません。

認証プロキシの背後に配置してください。プロキシは各送信先を認可し、クライアントが指定した URL およびトークンのヘッダーを置き換えて、対応するトークンを指定する必要があります。サーバーの送信ネットワークアクセスは、承認済みの送信先に制限してください。

許可リストがない場合、偽のリクエストトークンによって、内部サービスやメタデータサービスを含む、到達可能な任意の HTTP(S) サービスへリクエストが送信される可能性があります。

大規模なフリートで選択を有効にするには、GRAFANA_ALLOW_URL_OVERRIDE=true（または --allow-grafana-url-override）を設定します。送信先を制限するには、GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana（または --allowed-grafana-urls）も設定します。

送信先を選択する各 MCP リクエストに、次のヘッダーを指定します。

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

--server-auth-token が設定されている場合は、Authorization: Bearer <MCP caller token> も送信してください。これは MCP サーバーへの認証に使用され、選択した Grafana インスタンス用の X-Grafana-Service-Account-Token とは別のものです。プロキシはインスタンスごとに異なる Grafana トークンを送信できます。サーバーが設定済みのトークンをインスタンス間で共有することはありません。非推奨の X-Grafana-API-Key ヘッダーも使用できます。リクエストに Grafana トークンが含まれていない場合、URL ヘッダーは拒否されます。トークンを含むリクエストを受信するため、TLS を使用してください。

許可リストは、スキーム、ポート、パスを含む完全一致のベース URL に適用されます。ワイルドカードはサポートされていません。Grafana 認証は SSRF 対策にはなりません。

選択された URL に対して、サーバーは GRAFANA_SERVICE_ACCOUNT_TOKEN、GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE、GRAFANA_API_KEY、環境変数による基本認証、GRAFANA_EXTRA_HEADERS、クライアント証明書を使用しません。--tls-skip-verify が設定されていても、TLS 検証は有効のままです。設定済みの CA ファイルは引き続き適用されます。そのリクエストから明示的に転送されたヘッダーは引き続き適用されます。選択されたベース URL の範囲外へのリダイレクトや、その他の Grafana API リクエストはブロックされます。X-Grafana-URL を含まないリクエストでは、通常どおり GRAFANA_URL と環境変数の認証情報が使用されます。このオプションはストリーマブル HTTP のみを対象とします。SSE ではツール呼び出しにリクエストごとのヘッダーが渡されないため、使用できません。SSE で URL を選択すると、呼び出しに呼び出し元のトークンが使われず、失敗します。

デバッグとログ記録：

• --debug：詳細な HTTP リクエスト／レスポンスログを記録するデバッグモードを有効にします
• --log-level：ログレベル（debug、info、warn、error）— デフォルト：info

Grafana クライアントのオプション：

• --grafana-timeout：Grafana クライアントが行うリクエストの制限時間です。Go の期間文字列（例：10s、500ms）を指定します — デフォルト：10s
• --allow-cross-origin-redirects：Grafana の外部クライアントが、スキーム、ホスト、ポートのいずれかが異なる宛先へのリダイレクトを追跡することを許可します。デフォルトは false です。環境変数の代替設定は GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS です。有効にすると、Grafana の認証情報がリダイレクト先に送信される可能性があります。リクエストで選択された Grafana URL は、選択された宛先に固定されたままです。
• --include-args-in-spans：ツール呼び出しの引数を OpenTelemetry スパンに含めます。引数に PII が含まれないと分かっている場合、または本番環境以外でのみ有効にしてください — デフォルト：false

オブザーバビリティ：

• --metrics：/metrics の Prometheus メトリクスエンドポイントを有効にします
• --metrics-address：メトリクスサーバー用の別アドレス（例：:9090）です。空の場合、メトリクスはメインサーバーで提供されます
• --healthz-address：/healthz 用の別アドレス（例：:8080）です。空の場合、/healthz はメインサーバーで提供されます。2 つのアドレスが一致する場合、--metrics-address とリスナーを共有します。サイドリスナーでは Host／Origin の検証をスキップします。
• --slow-request-threshold：MCP リクエスト（ツール呼び出し、一覧取得、リソースの読み取りなど）の所要時間がこの期間を超えた場合にイベントをログに記録します。Go の期間文字列（例：500ms、5s）を指定します。デフォルトの 0 では、低速リクエストのログ記録は無効です。低速リクエストのログ記録のセクションを参照してください。
• --slow-request-log-level：低速リクエストイベントのログレベル（info または warn）— デフォルト：warn

匿名利用統計：

• --usage-stats：匿名利用統計の報告設定です。enabled、disabled、または log（送信されるレポートを stderr に出力し、送信はしません）を指定します。GRAFANA_USAGE_STATS 環境変数を上書きし、この環境変数は DO_NOT_TRACK を上書きします。認識されない値を指定した場合、報告は無効になります。匿名利用統計のセクションを参照してください。 ツールの設定：
• --enabled-tools：有効にするカテゴリーをカンマ区切りで指定します。デフォルトでは、admin、agento11y、assistant、athena、clickhouse、cloudlogging、cloudwatch、elasticsearch、examples、graphite、quickwit、runpanelquery、snowflakeを除くすべてのカテゴリーが有効です。無効なカテゴリーを有効にするには、リストに追加します（例："search,datasource,...,snowflake"）。
• --max-loki-log-limit：query_loki_logsの呼び出しごとに返すログ行の最大数です。デフォルトは100です。注：切り詰めを検出できるよう、この値はLokiサーバー側のmax_entries_limit_per_queryより少なくとも1小さい値に設定してください（ツールは、データがさらにあるかどうかを検出するため、内部でlimit+1をリクエストします）。
• --loki-guardrail-mode：query_loki_logsのLokiクエリコストに対するガードレールです。デフォルトはoffです。Lokiは、行フィルターのないログクエリに対してmax_query_bytes_readを適用しないため、広い範囲を対象とするセレクターはテラバイト単位のデータをスキャンする可能性があります。このガードレールでは、選択性の高いストリームセレクターを必須とし、有効な時間範囲（[30d]などの範囲ベクトルの期間を含む）に上限を設け、クエリ実行前にLokiのインデックス／統計情報を使ってバイト数を推定します。shadowは、ブロック対象となるクエリをログに記録しつつ実行を許可します（インデックス／統計情報の取得には引き続き時間がかかります）。enforceは、LLMが対応できる書き換え方法を提示してクエリを拒否します。VictoriaLogsでは、ガードレールはセレクター形式（{...}）のクエリにのみ適用されます。セレクターを解析できない場合（通常の波括弧を含まないLogsQL形式）は、クエリがそのまま通過し、バイト数の上限チェックは適用されません（低コストで利用できるインデックス推定がないため）。環境変数の代替設定：GRAFANA_LOKI_GUARDRAIL_MODE。
• --loki-guardrail-max-bytes：単一のquery_loki_logs呼び出しでスキャンできる最大バイト数です。Lokiのインデックス／統計情報APIを使用して推定します。デフォルトは107374182400（100 GiB）です。0にすると、バイト数の上限チェックが無効になります。環境変数の代替設定：GRAFANA_LOKI_GUARDRAIL_MAX_BYTES。
• --loki-guardrail-max-range：範囲ベクトルの期間を含む、単一のquery_loki_logs呼び出しにおける有効な時間範囲の最大値です。デフォルトは24hです。Goの期間文字列を受け付けます。0にすると、範囲チェックが無効になります。環境変数の代替設定：GRAFANA_LOKI_GUARDRAIL_MAX_RANGE。
• --loki-enforced-matchers：すべてのネイティブLokiクエリに追加されるLogQLラベルマッチャーです。読み取り可能なログストリームを制限します（例：environment=~"prod|staging"）。--disable-apiが必要です。Lokiクエリの適用を参照してください。
• --loki-label-enumeration-fallback：負の強制マッチャーで対象を絞り込めない場合のラベル列挙ツールの動作です。reject（デフォルト）またはunfilteredを指定します。Lokiクエリの適用を参照してください。
• --disable-search：検索ツールを無効にします
• --disable-datasource：データソースツールを無効にします
• --disable-incident：インシデントツールを無効にします
• --disable-prometheus：prometheusツールを無効にします
• --disable-write：書き込みツール（作成／更新操作）を無効にします
• --disable-query：クエリツール（データソースに対してクエリを実行するツール）を無効にします。メタデータツールとディスカバリーツールは引き続き利用できます
• --enable-query：--disable-writeが指定されていても、生SQLクエリツール（query_sql、query_influxdb）の登録を維持します。--enable-write-tools=query_sql,query_influxdbと同じです。この一般的な用途向けの省略形として用意されています。
• --enable-write-tools：--disable-writeが指定されていても登録を維持する個別のツール名をカンマ区切りで指定します。書き込み動作の範囲が限定され、個別に再有効化できるツールが対象です。カテゴリー全体が無効になっているツールには影響しません。たとえば、--enable-write-tools=generate_deeplinkを指定すると、--disable-writeが有効な場合でもURL短縮（shorten=true）が動作します。
• --disable-loki：lokiツールを無効にします
• --disable-elasticsearch：elasticsearchツールとopensearchツールを無効にします
• --disable-quickwit：quickwitツールを無効にします
• --disable-influxdb：InfluxDBツールを無効にします
• --disable-alerting：アラートツールを無効にします
• --disable-dashboard：ダッシュボードツールを無効にします
• --disable-oncall：オンコールツールを無効にします
• --disable-asserts：assertsツールを無効にします
• --disable-admin：adminツールを無効にします
• --disable-pyroscope：pyroscopeツールを無効にします
• --disable-navigation：ナビゲーションツールを無効にします
• --disable-rendering：レンダリングツール（パネル／ダッシュボードの画像エクスポート）を無効にします
• --disable-snapshot：スナップショットツールを無効にします
• --disable-cloudwatch：CloudWatchツールを無効にします
• --disable-cloudlogging：Google Cloud Loggingツールを無効にします
• --disable-examples：クエリ例ツールを無効にします
• --disable-sql：SQLデータソースツール（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL）を無効にします。エイリアス--disable-clickhouse、--disable-snowflake、--disable-athenaも使用できます。
• --disable-runpanelquery：パネルクエリ実行ツールを無効にします
• --disable-graphite：Graphiteツールを無効にします
• --disable-provisioning：プロビジョニングツールを無効にします
• --disable-agento11y：エージェントのオブザーバビリティツールを無効にします
• --disable-assistant：Grafana Assistantツールを無効にします
• --disable-docs：ドキュメントツールを無効にします

読み取り専用モード

--disable-write フラグを指定すると、MCP サーバーを読み取り専用モードで実行し、Grafana インスタンスへの書き込み操作をすべて防止できます。次のように、安全な読み取り専用アクセスを提供したい場合に便利です。

• 読み取り専用権限が制限されたサービスアカウントを使用する場合
• 変更機能を付与せずに、AI アシスタントにオブザーバビリティデータを提供する場合
• 書き込みアクセスを制限すべき本番環境で実行する場合
• 意図しない変更を防ぎたいテストおよび開発の場面

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

ダッシュボードツール：

• update_dashboard

フォルダーツール：

• create_folder

インシデントツール：

• create_incident
• add_activity_to_incident
• update_incident

アラートツール：

• alerting_rules_write（作成、更新、削除の操作）
• alerting_silences_write（作成、更新、削除の操作）
• alerting_routing_write（create_contact_point 操作）

OnCall ツール：

• update_alert_group

アノテーションツール：

• create_annotation
• update_annotation
• delete_annotation

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

• create_snapshot
• delete_snapshot

ナビゲーションツール：

• generate_deeplink（shorten=true は無視され、完全な URL が返されます。URL 短縮を有効にするには、--enable-write-tools=generate_deeplink を指定してください）

Raw-SQL クエリツール：

これらのツールはクエリを検査せず、指定された内容をそのまま実行するため、データソースの認証情報で許可されている場合は書き込みが可能です。たとえば、query_sql は DROP TABLE を実行し、query_influxdb は DELETE を実行します。そのため、読み取り専用モードではこれらのツールが削除されます。データソースの認証情報が読み取り専用だと確認できている場合は、--enable-query を指定してこれらのツールを有効にできます。

• query_sql
• query_influxdb

エージェントオブザーバビリティツール：

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

すべての読み取り操作は引き続き利用できるため、ダッシュボードのクエリ、PromQL／LogQL クエリの実行、リソースの一覧表示、データの取得が可能です。書き込みを表現できないクエリ言語である PromQL、LogQL、TraceQL、Elasticsearch DSL、Graphite、CloudWatch のクエリツールは、読み取り専用モードでも引き続き利用できます。削除されるのは、上記の Raw-SQL ツールのみです。

クエリ無効モード

--disable-query フラグを指定すると、データソースに対してクエリを実行するすべてのツールが削除され、メタデータや検出用のツールはそのまま利用できます。これは、サービスアカウントに datasources:read 権限はあるものの datasources:query 権限がない場合など、データソース、ダッシュボード、メトリクス名、ラベル、テーブルスキーマといった情報を確認できる一方で、コストのかかるクエリやデータを露出させる可能性のあるクエリは実行させたくない場合に便利です。

3 つのクエリ設定のうち最も強力で、--enable-query より優先されます。

フラグ	安全なクエリツール（query_prometheus、query_loki_logs、run_panel_query、…）	生 SQL クエリツール（query_sql、query_influxdb）
(none)	登録される	登録される
--disable-write	登録される	登録されない
--disable-write --enable-query	登録される	登録される
--disable-query	登録されない	登録されない
--disable-query --enable-query	登録されない	登録されない

--disable-query が有効な場合、次のツールは登録されません。

Prometheus ツール：

• query_prometheus
• query_prometheus_histogram

Loki ツール：

• query_loki_logs
• query_loki_patterns

query_loki_stats と analyze_loki_labels は登録されたままです。どちらもセレクターをデータソースに送信しますが、ログの内容ではなく、インデックスを読み取ってストリーム数、チャンク数、バイト数を返します。

Elasticsearch/OpenSearch および Quickwit ツール：

• query_elasticsearch
• query_quickwit

InfluxDB ツール（上記のとおり --disable-write によっても削除されます）：

• query_influxdb

SQL データソースツール（上記のとおり --disable-write によっても削除されます）：

• query_sql

Graphite ツール：

• query_graphite
• query_graphite_density

CloudWatch ツール：

• query_cloudwatch
• query_cloudwatch_logs

Google Cloud Logging ツール：

• query_cloud_logging

Pyroscope ツール：

• query_pyroscope

パネルクエリ実行ツール：

• run_panel_query

elasticsearch、quickwit、influxdb、runpanelquery の各カテゴリにはほかのツールがないため、クエリが無効な場合はツールが一切登録されません。それ以外の各カテゴリにある関連ツール（list_prometheus_metric_names、list_loki_label_values、describe_sql_table、list_cloudwatch_metrics、list_cloud_logging_projects など）は引き続き利用できます。

--disable-query はクエリツールと grafana_api_request の /api/ds/query への POST パスを制限しますが、データソースへのすべてのルートを制限するわけではありません。読み取り専用モードでは、クエリツールが有効な場合に限り、grafana_api_request で /api/ds/query への POST が許可されます（生 SQL ツールと同じ制限が適用され、--enable-query で上書きされない限り --disable-write によってブロックされます）。サーバー側でパネルをレンダリングする get_panel_image には影響しません。

クライアント TLS 設定（Grafana 接続用）：

• --tls-cert-file：クライアント認証用 TLS 証明書ファイルのパス
• --tls-key-file：クライアント認証用 TLS 秘密鍵ファイルのパス
• --tls-ca-file：サーバー検証用 TLS CA 証明書ファイルのパス
• --tls-skip-verify：TLS 証明書の検証をスキップします（安全ではありません）

サーバー TLS 設定（streamable-http トランスポートのみ）：

• --server.tls-cert-file：サーバー HTTPS 用 TLS 証明書ファイルのパス
• --server.tls-key-file：サーバー HTTPS 用 TLS 秘密鍵ファイルのパス

使用方法

この MCP サーバーは、ローカルの Grafana インスタンスと Grafana Cloud の両方で動作します。Grafana Cloud の場合は、以下の設定例で http://localhost:3000 の代わりにインスタンス URL（例：https://myinstance.grafana.net）を使用してください。

1. サービスアカウントトークン認証を使用する場合は、使用するツールに必要な権限を持つサービスアカウントを 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 ヘッダー： ストリーマブル HTTP トランスポートを使用する場合は、X-Grafana-Org-Id を設定します（環境変数よりヘッダーが優先されるため、既定の組織も設定できます）。

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

動的な組織選択（呼び出しごと）

上記の方法では、接続全体で組織が固定されます。1 つの接続からツール呼び出しごとに異なる組織を対象にするには、--dynamic-multi-org フラグを指定してサーバーを起動します。これは既定で無効です。

有効にすると、すべてのツールで省略可能な orgId 引数が使用でき、呼び出しごとに接続の組織を上書きします（X-Grafana-Org-Id ヘッダーと、アプリプラットフォーム API の場合は解決された Kubernetes 名前空間の両方に適用されます）。プロキシされたデータソースツールは、認証情報でアクセスできるすべての組織を対象に検出されます。orgId を省略した呼び出しでは、接続の既定の組織が使用されます。

これは、複数の組織に属する認証情報（ユーザーや代理実行の ID など）でのみ機能します。サービスアカウントトークンは、引き続き単一の組織に紐付けられます。有効な orgId の値を確認するには、user_info ツールを使用してください。

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

SOCKS5 プロキシ

GRAFANA_SOCKS5_PROXY 環境変数を使用すると、このサーバーから Grafana へのすべてのリクエストを SOCKS5 プロキシ経由でルーティングできます。プロキシの適用範囲は、このサーバーの Grafana 通信に限られます。グローバルな HTTP_PROXY／HTTPS_PROXY 環境変数は変更されず、この変数を設定すると、Grafana の通信に限り、プロキシの選択でそれらの設定が上書きされます。他の MCP サーバーやシェルセッションには影響しません。設定されていない場合、動作は変わりません。

URL には socks5:// または socks5h:// スキームを使用する必要があります（Go ではどちらも同じ扱いで、ホスト名の解決はプロキシに委ねられます）。また、次の例のように認証情報を含めることもできます：socks5://user:[email protected]:1080。

例：

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

無効なプロキシ URL は起動時のエラーになります。プロキシ経由の接続を実行時に確立できない場合、Grafana への通信を直接送信することなく、サーバーは接続を拒否します。

クライアントからのヘッダー転送（Streamable-HTTP のみ）

MCP サーバーが SSO を処理するゲートウェイまたはリバースプロキシ（OIDC を使用する AWS ALB など）の背後で動作する場合、Grafana がリクエストを認証済みユーザーに関連付けられるよう、各ユーザーのセッション Cookie を Grafana に渡す必要があります。GRAFANA_FORWARD_HEADERS 環境変数を使用すると、受信した HTTP リクエストから、送信するすべての Grafana API リクエストにコピーするヘッダー名をカンマ区切りの許可リストで指定できます。

これは streamable-http（-t streamable-http）トランスポートを使用する場合にのみ適用されます。stdio モードまたは SSE モードには影響しません。

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

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

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

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

転送されたヘッダーは、GRAFANA_EXTRA_HEADERS で定義されたヘッダーと統合されます。両方に同じヘッダー名がある場合、そのリクエストでは受信したリクエストの値が優先されます。

例外はトレースコンテキストヘッダー（traceparent、tracestate、baggage）です。サーバー自身がトレースコンテキストを伝播するため、転送された値がサーバーによって挿入される値を上書きすることはありません。オブザーバビリティを参照してください。

2. mcp-grafana のインストールには、いくつかの方法があります。

   • uvx（推奨）： uv がインストールされていれば、追加のセットアップは必要ありません。uvx がサーバーを自動的にダウンロードして実行します。

     uvx mcp-grafana
     

   • Docker イメージ：Docker Hub のビルド済み Docker イメージを使用します。

     重要：Docker イメージのエントリポイントは、デフォルトで MCP サーバーを SSE モードで実行するよう設定されています。ただし、ほとんどのユーザーは、Claude Desktop などの AI アシスタントと直接統合するために STDIO モードを使用します。

     1. STDIO モード：stdio モードを使用するには、-t stdio でデフォルトを明示的に上書きし、標準入力を開いたままにするために -i フラグを指定する必要があります。

     docker pull grafana/mcp-grafana
     # ローカルの 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
     # 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 モードには影響しません。呼び出し元認証を参照してください。

     2. 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
     

     3. ストリーマブル 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 ストリーマブル HTTP モードの場合:

     docker pull grafana/mcp-grafana
     docker run --rm -p 8443:8443 \
       -v /path/to/certs:/certs:ro \
       -e GRAFANA_URL=http://localhost:3000 \
       -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
       -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
       grafana/mcp-grafana \
       -t streamable-http \
       -addr :8443 \
       --server.tls-cert-file /certs/server.crt \
       --server.tls-key-file /certs/server.key
     

   • バイナリのダウンロード: リリースページから mcp-grafana の最新リリースをダウンロードし、$PATH に配置します。

   • ソースからのビルド: Go ツールチェーンがインストールされていれば、ソースからビルドしてインストールすることもできます。GOBIN 環境変数を使用して、バイナリをインストールするディレクトリを指定します。このディレクトリも $PATH に含まれている必要があります。

     GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest
     

   • Helm を使用した Kubernetes へのデプロイ: Grafana helm-charts リポジトリの Helm チャートを使用します。

     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
     

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

   uvx を使用する場合:

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

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

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

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

Docker を使用する場合:

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

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

VSCode でリモート MCP サーバーを使用する場合

VSCode を使用していて、MCP サーバーを SSE モード (トランスポートを上書きせずに 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 データソースクライアント
• インシデント管理クライアント
• アラートクライアント
• 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）を使用する場合、HTTP の代わりに HTTPS で接続を提供するよう MCP サーバーを設定できます。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

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

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

**注：**ヘルスチェックエンドポイントは、SSE または Streamable HTTP トランスポートの使用時のみ利用できます。stdio トランスポート（-t stdio）では HTTP サーバーを公開しないため、利用できません。

匿名の使用統計

サーバーは、自身に関する匿名の使用統計を Grafana Labs に報告できます。報告されるのは、呼び出されたツール、その呼び出しのうち失敗した数、サーバーの設定です。1回の報告の対象は、1人のユーザーや1つの会話ではなく、1つのサーバープロセスです。報告は4時間ごと、およびシャットダウン時に1回送信されます。報告はデフォルトで有効です。無効にするには、--usage-stats=disabled、GRAFANA_USAGE_STATS=disabled、またはDO_NOT_TRACK=1を設定してください。

ツールの引数、リソース名、クエリ、ログ行、エラーメッセージ、認証情報は送信されません。フラグは値ではなく名前のみ記録され、Grafana インスタンスはcloudまたはself_hostedとしてのみ記述されます。URL、ホスト名、スタックのスラッグ、組織名が送信されることはありません。ユーザー、セッション、クライアントごとの情報は一切ありません。通信にはセッション識別子が含まれず、特定のクライアントにツール呼び出しを関連付ける方法もありません。

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

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

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

DO_NOT_TRACK=1を設定すると、ツール間で共通のDO_NOT_TRACK規約に従って報告も無効になります。効果があるのは1だけで、無効化のみが可能です。また、--usage-statsとGRAFANA_USAGE_STATSはこの設定より優先されるため、ホストでこの変数をグローバルに設定していても、個別のサーバーで報告を再度有効にできます。

GRAFANA_USAGE_STATS_ENDPOINTを設定すると、送信先を変更できます。報告を無効にする設定ではありません。

全フィールドの一覧、送信されない情報、データの読み取り方と制限事項については、匿名の使用統計をご覧ください。

オブザーバビリティ

MCP サーバーは、Prometheus メトリクス、OpenTelemetry 分散トレーシング、OpenTelemetry ログエクスポートに対応しており、OTel MCP セマンティック規約に準拠しています。トレーシングとログエクスポートは標準のOTEL_*環境変数で設定でき、あらゆるトランスポートで動作します。

注： mcp-grafana は現在、トレースとログの両方で OTLP/gRPC トランスポートのみをサポートしています。OTEL_EXPORTER_OTLP_PROTOCOL（およびその_TRACES_PROTOCOL／_LOGS_PROTOCOL版）は使用されず、常に gRPC が使用されます。

メトリクス

SSE またはストリーマブル 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）
http_server_request_duration_seconds	ヒストグラム	HTTP サーバーリクエストの所要時間（otelhttp による）

注： メトリクスは SSE またはストリーマブル HTTP トランスポートを使用する場合にのみ利用できます。stdio トランスポートでは利用できません。

Loki コストガードレール（--loki-guardrail-mode）を有効にすると、その判定を記録するカウンターがさらに 4 つ追加されます。

メトリクス	種類	説明
mcp_loki_guardrail_admitted_total	カウンター	有効なすべてのチェックを通過したクエリ（ラベル：backend）
mcp_loki_guardrail_would_block_total	カウンター	shadow モードでチェックに失敗したものの、そのまま実行されたクエリ（ラベル：backend、reason）
mcp_loki_guardrail_blocked_total	カウンター	enforce モードで拒否されたクエリ（ラベル：backend、reason）
mcp_loki_guardrail_fail_open_total	カウンター	ガードレールで評価できず、許可されたクエリ（ラベル：backend、cause）

reason は selector、range、bytes のいずれかで、cause は unparseable、estimate_failed のいずれかです。backend は loki、victorialogs、unknown のいずれかです。複数のチェックに該当したクエリは、最初に実行されたチェック（selector、次に range、最後に bytes）のラベルで 1 回だけカウントされるため、4 つのカウンターでガードレールの対象となったクエリ全体が分類されます。shadow から enforce へのロールアウト中の読み取り方については、オブザーバビリティを参照してください。

ライブラリを組み込む場合は、GrafanaConfig.MeterProvider（GrafanaConfig.Logger に対応するメトリクス用設定）を設定してください。ガードレールはツールハンドラー内で動作するため、コンストラクターのオプションがありません。また、プロセスに noop のグローバル MeterProvider を設定すると、すべての記録が破棄されてしまいます。

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

--slow-request-threshold フラグを指定すると、MCP リクエスト（ツール呼び出し、リスト表示、リソース読み取りなど）が指定した時間を超えたときに、構造化ログイベントが出力されます。デバッグログ全体でログがあふれるのを避けながら、遅いクエリやツール呼び出しを診断するのに役立ちます。

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

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

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

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

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

遅いリクエストのログ記録は stdio を含むすべてのトランスポートで機能し、--metrics は不要です。デフォルトのしきい値 0 では完全に無効になります。プロキシされたツールは tools/call を経由するため、自動的に対象になります。

トレーシング

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

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

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

ツール呼び出しのスパンには 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）が設定されている場合、サーバーは既存のプレーンテキストの標準エラー出力に加えて、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 ログを有効にしても、標準エラー出力へのログ出力に変更はありません。引き続きコンテナーログを利用するか、必要に応じて標準エラー出力を/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

Loki クエリの適用制御

--loki-enforced-matchers を使用すると、すべてのネイティブ Loki クエリに固定の LogQL ラベルマッチャーを AND で追加し、サーバーが読み取れる Loki ログストリームを制限できます。データソースに公開してはならないストリーム（機密情報を含む可能性のあるログなど）がある一方で、Grafana や Loki のレイヤーでアクセスを制限できない場合に便利です（OSS には、データソース単位またはユーザー単位のラベルアクセス制御がありません）。

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

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

仕組み：

• マッチャーは起動時に一度解析されます（入力が無効な場合、サーバーの起動は中止されます）。その後、各クエリ内のすべてのストリームセレクターに追加されます。Loki はセレクター内のマッチャーを AND で結合するため、ユーザークエリでできるのは、適用された範囲内で結果を絞り込むことだけで、範囲を広げることはできません。ポリシーに反するユーザーセレクター（除外設定のもとで {namespace="vault"} を要求するなど）は、単に結果を返しません。
• query_loki_logs、query_loki_stats、query_loki_patterns、list_loki_label_names、list_loki_label_values に適用されます。
• フェイルクローズ方式です。解析できないクエリは、フィルターなしで送信されるのではなく、拒否されます。
• VictoriaLogs データソースは安全に書き換えられない LogsQL を使用するため、適用制御が有効な間は全面的に拒否されます。
• 否定のみのマッチャーでは、ラベル列挙エンドポイントの対象を絞り込めません（Loki は正のマッチャーを含まないセレクターを拒否します）。このケースは --loki-label-enumeration-fallback で制御してください（既定では reject、または unfiltered を指定すると、対象を絞らずにラベルのメタデータを列挙できます。ログ行は公開されません）。正のマッチャーや許可リストのマッチャーには影響しません。

重要

適用制御の対象は Loki クエリツールのみです。他のツールは適用制御されたバックエンドを経由せずに Loki のログデータへアクセスできるため、制限を確実に適用するには、次のツールも無効にする必要があります。

• --disable-api — grafana_api_request は Loki データソースプロキシに直接クエリを実行でき、完全に迂回できます。
• --disable-rendering — get_panel_image はサーバー側で Loki パネルをレンダリングし、制限されていないログ行を含む画像を生成します。
• --disable-assistant — ask_assistant は Grafana Assistant に処理を委譲します。Grafana Assistant はサーバー側で、すべてのストリームから Loki のデータを読み取ります。このツールは書き込みツールが有効な場合にのみ登録されるため、--disable-write でも無効になります。

サーバーは起動時に、これらのツールのうち有効なままのものを名前とともに警告します。 run_panel_query は安全です（適用制御されたクエリ経路を再利用します）。Tempo ツールがクエリするのはトレースであり、Loki ログではないため、迂回経路にはなりません。ダッシュボードのスナップショット（--disable-snapshot）にも、適用制御の対象外で取得されたログパネルのデータが埋め込まれる場合があります。

トラブルシューティング

Grafana バージョンとの互換性

データソース関連のツールを使用した際に次のエラーが発生する場合：

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

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

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

開発

コントリビューションを歓迎します！まずはCONTRIBUTING.mdをお読みください。このサーバーに含めるべき内容や、提案方法について説明しています。

新しいツールを追加する場合は、コードを書く前にツールの提案を作成してください。デフォルトで有効なツールは、すべてのユーザーのすべてのリクエストでモデルに送信されるため、完成したプルリクエストを却下するよりも、アイデアについて事前に話し合いたいと考えています。バグ修正、ドキュメント、テスト、既存ツールへの新しいパラメーターの追加には提案は不要です。そのままPRをお送りください。

このプロジェクトはGoで記述されています。ツールのバージョンと開発タスクはmise.tomlに記載されています。miseをインストールし、mise installを実行して固定されたツールを取得してから、mise tasksでタスクを一覧表示してください。

ローカルでサーバーをSTDIOモード（ローカル開発時のデフォルト）で実行するには、次のコマンドを使用します。

mise run run

ローカルでサーバーをSSEモードで実行するには、次のコマンドを使用します。

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

カスタムビルドしたDockerイメージ内で、SSEトランスポートを使用してサーバーを実行することもできます。公開済みのDockerイメージと同様に、このカスタムイメージのエントリーポイントはデフォルトでSSEモードになります。イメージをビルドするには、次のコマンドを使用します。

mise run build-image

イメージをSSEモード（デフォルト）で実行するには、次のコマンドを使用します。

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

代わりにSTDIOモードで実行する必要がある場合は、トランスポート設定を上書きします。

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

テスト

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

1. 単体テスト（外部依存関係は不要です）：

mise run test-unit

次のコマンドでも単体テストを実行できます。

mise run test

2. 統合テスト（Dockerコンテナーが起動している必要があります）：

mise run test-integration

3. クラウドテスト（Grafanaのクラウドインスタンスと認証情報が必要です）：

mise run test-cloud

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

より包括的な統合テストには、ポート3000でローカルにGrafanaインスタンスを起動しておく必要があります。Docker Composeを使用して起動できます。

docker-compose up -d

ツールを追加する場合は、統合テストも追加してください。既存のテストが参考になります。

Lint

コードをLintするには、次のコマンドを実行します。

mise run lint

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

mise run lint-jsonschema

詳しくはJSONSchema Linterのドキュメントをご覧ください。

ライセンス

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