ClaudeでGrafanaを操作するmcp-grafanaの導入とRBAC設計

Grafana公式のMCPサーバーmcp-grafanaを使うと、Claude Codeからダッシュボード検索やデータソース確認、アラート管理までを自然言語で扱えます。導入自体はuvxコマンド1つで終わりますが、実務で使うにはサービスアカウントのRBACスコープ設計と、扱わないツールカテゴリを止める作業が要ります。この2つを詰めずにEditorロールをそのまま割り当てると、読み取りだけのつもりが書き込み権限まで渡ってしまいます。

mcp-grafanaとは — Grafana公式が配布するMCPサーバー

mcp-grafanaは、Grafana Labsがgrafana/mcp-grafanaとして公開しているGo製のMCPサーバーです。ダッシュボード、データソース、Prometheus、Loki、アラート、Incident、OnCallなど、Grafanaエコシステムの主要機能にMCP経由でアクセスできます。Grafana Labsの公式orgが直接メンテナンスしているMCPサーバーです。

対応するデータソースはPrometheus・Loki・ClickHouse・CloudWatch・Elasticsearch・OpenSearch・Snowflake・Athena・InfluxDB・Graphite・Pyroscopeと幅広く、Grafana 9.0以降での動作を前提にしています。9.0より前のバージョンでは、データソース関連のAPIエンドポイントが存在しないため一部のツールが失敗します。

Claude Codeにmcp-grafanaを追加する

インストール方法はuvx(推奨)・Dockerイメージ・バイナリダウンロード・Goのソースビルド・Helmチャートの5通りがあります。uvが入っていればuvxが最短です。

先にGrafana側でサービスアカウントを作成し、トークンを発行しておきます。Grafanaの管理画面から作成するか、後述のRBACスコープを絞ったうえで発行してください。

claude mcp add-json grafana \
  '{"command":"uvx","args":["mcp-grafana"],"env":{"GRAFANA_URL":"https://myinstance.grafana.net","GRAFANA_SERVICE_ACCOUNT_TOKEN":"<サービスアカウントトークン>"}}'

ローカルのGrafanaに繋ぐ場合はGRAFANA_URLをhttp://localhost:3000に置き換えます。認証にユーザー名・パスワードを使う構成や、環境変数GRAFANA_SERVICE_ACCOUNT_TOKEN_FILEでトークンをファイルから読ませる構成にも対応しており、後者はKubernetesでSecretをボリュームマウントしてトークンをローテーションする運用に向きます(トークンはリクエストのたびにファイルから読み直されるため、サーバー再起動なしで新しいトークンに切り替わります)。

Docker版を使う場合は、コンテナのエントリポイントが既定でSSEモードになっている点に注意してください。Claude Codeのような標準入出力(stdio)クライアントから使うには、-t stdioを明示的に付ける必要があります。

docker run --rm -i \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<サービスアカウントトークン> \
  grafana/mcp-grafana -t stdio

サービスアカウントとRBACスコープを設計する

mcp-grafanaのツールはそれぞれ固有のRBAC権限とスコープを要求します。たとえばsearch_dashboardsにはdashboards:read権限とdashboards:*(または特定UIDのdashboards:uid:abc123)のスコープが要ります。使うツールが増えるほど、必要な権限の組み合わせも増えます。

細かいスコープ設計が面倒なら、サービスアカウントに組み込みロールEditorを割り当てる近道もあります。読み書き両方の広い権限を一括で得られますが、最小権限の原則からは外れます。利便性と権限の絞り込み、どちらを優先するかで選んでください。

最小権限で運用するなら、用途ごとにスコープを絞ります。

Grafana Incident・SiftのツールだけはRBACの細かいスコープではなく、Viewer(参照系)/Editor(作成・更新系)という基本ロールで制御される点も覚えておくと迷いません。Grafana OnCallのツールはgrafana-oncall-app.schedules:readのようなプラグイン固有のパーミッションが要ります。

カテゴリ単位でツールを絞り込む — --enabled-toolsと --disable-〈category〉

ツールはカテゴリ(Dashboard、Prometheus、Loki、OnCall、Adminなど)に分類されていて、カテゴリ単位で有効・無効を切り替えられます。特定カテゴリを止めるなら--disable-<category>、有効化リストを明示するなら--enabled-toolsにカンマ区切りでカテゴリ名を渡します。

既定ではadmin・agento11y・assistant・athena・clickhouse・cloudwatch・elasticsearch・examples・graphite・quickwit・runpanelquery・snowflakeの12カテゴリが無効です。使わないデータソースの接続情報までモデルに晒さないための既定になっています。

OnCall連携だけを止めたい、あるいはダッシュボード操作の役割からOnCallツールを切り離したいときは、次のように起動します。

uvx mcp-grafana --disable-oncall

逆にAdminカテゴリを使いたいなら--enabled-toolsに明示で加えます。

uvx mcp-grafana --enabled-tools "search,dashboard,datasource,prometheus,loki,admin"

--enabled-toolsはリストを丸ごと置き換える指定です。既定で有効なsearchやdashboardまで含めて書き直す必要があるため、個別カテゴリだけ足したいときは--enabled-toolsより--disable-<category>の積み上げのほうが事故が少なくなります。

用途別に絞り込むカテゴリの組み合わせ

読者の運用目的に応じて、有効化するカテゴリの組み合わせは大きく変わります。

Run Panel Query・Query Examples・InfluxDB・ClickHouse・CloudWatch・Graphite・Athena・Snowflake・Elasticsearch/OpenSearch・Quickwit・Agent Observability・Grafana Assistant・Adminの各カテゴリは既定で無効です。必要になったときだけ--enabled-toolsに加えます。

書き込みを禁止する — --disable-writeで読み取り専用運用

観測データを見せるだけで変更はさせたくない、という運用には--disable-writeが使えます。ダッシュボードの更新、Incidentの作成・更新、アラートルールの作成・更新・削除、OnCallのアラートグループ更新、注釈の作成・更新・削除、スナップショットの作成・削除といった書き込み系ツールがまとめて登録から外れます。

ClickHouse・Snowflake・Athena・InfluxDB向けの生SQLツールは、クエリの中身を検査せずそのまま実行するためDROP TABLEのような破壊的な操作も通してしまいます。--disable-writeはこの4つも道連れに無効化します。読み取り専用の認証情報を使っていると分かっている場合に限り、--enable-queryを足せば生SQLツールだけ復活させられます。

さらに絞りたいなら--disable-queryです。データソースへのクエリを実行するツールを丸ごと止め、データソース一覧やメトリクス名、ラベル、テーブルスキーマといったメタデータ・発見系のツールだけを残します。サービスアカウントにdatasources:readはあってもdatasources:queryが無い、という構成に対応させたいときに向きます。

複数組織(Organization)にまたがる場合のRBAC設計

Grafanaインスタンスが複数の組織(Organization)を持つ構成では、サービスアカウントが所属する組織以外のデータにはそのままアクセスできません。接続先の組織を固定するなら、環境変数GRAFANA_ORG_IDに数値の組織IDを指定します。SSE / streamable-httpトランスポートでは、接続ごとにX-Grafana-Org-Idヘッダーで上書きすることもでき、ヘッダーが環境変数より優先されます。

1接続で呼び出しごとに異なる組織を切り替えたい場合は、サーバー起動時に--dynamic-multi-orgを付けます。既定では無効です。有効化すると各ツールが任意のorgId引数を受け取れるようになり、その呼び出しだけ接続既定の組織を上書きします。ただしこれはユーザー認証情報や委任認証情報のように複数組織へまたがる資格情報でのみ機能し、サービスアカウントトークンは発行時点の単一組織に固定されたままです。どのorgIdが有効かはuser_infoツールで調べられます。

サービスアカウント単位でRBACスコープを絞る設計をしている場合、組織をまたぐ運用は「組織ごとに専用のサービスアカウントを用意する」のが素直な選択です。--dynamic-multi-orgは、ユーザー個人の認証情報をそのままMCP経由で使わせるような構成でのみ検討する位置づけになります。

よくあるつまずき

GRAFANA_API_KEYは非推奨: 古い手順では環境変数GRAFANA_API_KEYを使っていますが、現在はGRAFANA_SERVICE_ACCOUNT_TOKENへの移行が案内されています。旧変数名も後方互換で動きますが、非推奨警告が出ます。

バイナリ導入でError: spawn mcp-grafana ENOENT: $PATHにバイナリが無いか、Claude側の設定でフルパスを指定していないと起きます。commandにバイナリの絶対パスを書けば解決します。

Dockerの既定モードに気づかない: Dockerイメージのエントリポイントは既定でSSEモードです。-t stdioを付け忘れると、Claude Codeとの標準入出力接続がそのまま失敗します。

Grafana 9.0未満でのgetDataSourceByUidBadRequest: /datasources/uid/{uid}エンドポイントはGrafana 9.0で追加されたため、それより古いインスタンスではデータソース関連のツールが400エラーで落ちます。インスタンスのアップグレードが唯一の解決策です。

カテゴリを絞ったつもりでスコープが広いまま: --disable-oncallのようなカテゴリ制限は、あくまでMCPサーバーがどのツールを公開するかの制御です。サービスアカウント自体にdatasources:*のような広いスコープを与えていれば、grafana_api_requestのような汎用ツール経由で同じデータへ別ルートからアクセスできてしまいます。カテゴリ単位の制限とRBACスコープの絞り込みは、どちらか一方では足りません。

まとめ

mcp-grafanaの導入自体はuvx mcp-grafanaとサービスアカウントトークンだけで動き始めます。実務で安全に使うための分かれ目は、①サービスアカウントのRBACスコープを用途に応じて絞る、②--disable-<category>または--enabled-toolsで扱わないカテゴリのツールを公開しない、③変更させたくない環境では--disable-write(必要なら--disable-queryまで)を足す、の3点です。ダッシュボード運用チームがまず導入し、OnCall対応やLoki中心のログ調査は別のサービスアカウント・別のカテゴリ構成で分離するのが実務では扱いやすくなります。