Claude Media
Claude CodeのGrafana Assistantプラグインで、CLI操作のスキルを使う手順
Claude CodeClaude連携チュートリアル

Claude CodeのGrafana Assistantプラグインで、CLI操作のスキルを使う手順

Grafana Labsのgrafana-assistantプラグインは、grafana-assistant CLIの使い方を教えるスキル1本とルール1本の小さな構成です。入れ方、前提のCLI、Claude Codeで効く範囲を示します。

読了目安 約14分

grafana-assistantは、Grafana Labsが配布するClaude Code用プラグインです。中身はgrafana-assistantコマンドの使い方を教えるスキル1本と、Grafana MCPツールの使い方のルール1本だけ。MCPサーバーは含まれません。

つまり、入れても監視データに直接つながるわけではありません。つなぐのは、別途入れたgrafana-assistant CLIです。このプラグインは、Claude CodeがそのCLIを正しい順序で呼べるようにする手引きにあたります。

3つのGrafanaプラグインのどれを入れるか

Grafana公式のマーケットプレイスには、似た名前のプラグインが3つあります。まず自分の用途がどれかを決めます。

使う環境入れるもの
Grafana Cloudをclaude.ai・Claude Desktop・モバイル・Coworkで使う入れるものGrafana Cloudコネクタ
Grafana CloudをClaude Codeなどで使う入れるものgrafana-cloud-mcpプラグイン
セルフホストのGrafana、またはサービスアカウントトークンで使う入れるものgrafana-mcpプラグイン
grafana-assistant CLIをClaude Codeから呼びたい入れるものgrafana-assistantプラグイン(本記事)

grafana-cloud-mcpは、ホスト型のMCPサーバー(https://mcp.grafana.com/mcp)と、60以上のツールを説明するスキルをまとめたものです。grafana-mcpは、Dockerで動くローカルのMCPサーバーを入れます。この2つはGrafanaのデータを直接読み書きするためのもので、grafana-assistantとは役割が違います。

Grafana MCPの導入とRBACはmcp-grafanaの導入とRBAC設計で扱っています。

プラグインの入れ方

Grafanaのリポジトリ自体がマーケットプレイスなので、先にそれを追加してから個別のプラグインを入れます。

/plugin marketplace add grafana/ai-marketplace
/plugin install grafana-assistant@grafana-ai-marketplace

grafana-ai-marketplaceは、リポジトリのmarketplace.jsonに書かれたマーケットプレイス名です。このファイルには、grafana-assistant・grafana-mcp・grafana-cloud-mcpの3つが登録されています。

/plugin installはセッション内では即時には入れず、プラグインの詳細パネルを開いてスコープを選ばせます。スコープは次の2つが基本です。

  • ユーザースコープ: 自分のマシンのすべてのプロジェクトで有効
  • プロジェクトスコープ: そのリポジトリの全員で有効(.claude/settings.jsonに書かれる)

プロジェクトスコープは設定ファイルに有効化の記述が入るだけで、各メンバーのマシンへ自動では入りません。チームで使うなら、各自がclaude plugin install grafana-assistant@grafana-ai-marketplace --scope projectを一度実行します。

claude.comのマーケットプレイスページにも「Install in Claude Code」があります。配布元はGrafana、プラグインの説明は「Skills and rules for developing and using the Grafana Assistant app and CLI」です。

同梱されているのはスキル1本とルール1本

プラグインのバージョンは0.2.0、ライセンスはApache-2.0です。READMEが挙げる構成要素は2つだけです。

ファイル内容
skills/grafana-assistant-cli/SKILL.md内容grafana-assistant CLIでGrafana AssistantをA2A API経由で使う手順
rules/grafana-assistant.mdc内容Grafana MCPツールを効率よく使うためのベストプラクティス

スキルの説明文には「grafana-assistant」「Grafana Assistant CLI」「assistant tunnel」という語が入っています。スキルの起動条件は、この説明文に書かれています。

スキルが前提にするgrafana-assistant CLI

スキルは、grafana-assistantバイナリが$PATHにすでにあることを前提にしています。しかも「自動でインストールしない」と明記され、コマンドが見つからなければ止まってユーザーに導入を促す作りです。

CLIの入手先は、Grafanaのassistant-cliリポジトリ(ビルド済みバイナリとDockerイメージ)です。プラグインを入れてもCLIは入りません。先にCLIを用意します。

認証と接続先の設定

スキルに書かれたセットアップは次の4コマンドです。

grafana-assistant config set-instance mystack \
  --url https://mystack.grafana.net
grafana-assistant config use-instance mystack
grafana-assistant auth   # ブラウザでPKCE認証
grafana-assistant chat   # 対話チャットを開始

ブラウザ認証には「Assistant CLI User」ロールが要ります。Editor以上のロールには最初から含まれます。カスタムロールならgrafana-assistant-app.tokens:access権限を足します。

設定ファイルは次の順で探され、最初に見つかったものが使われます。

  1. 環境変数GRAFANA_ASSISTANT_CONFIGが指すファイル
  2. カレントディレクトリの./grafana-assistant.yaml(--local指定時)
  3. ~/.config/grafana-assistant/config.yaml

資格情報の優先順位は、--urlと--tokenフラグ、環境変数GRAFANA_URLとGRAFANA_SA_TOKEN、--instanceフラグ、設定ファイルのcurrent-instanceの順です。サービスアカウントのトークンをファイルに平文で置きたくないときは、設定ファイルでtoken: ${GRAFANA_PROD_TOKEN}のように環境変数を参照できます。

Claude Codeからの呼び方: promptとcontextId

エージェントから使う主役は、1回きりの質問を投げて答えを受け取るpromptサブコマンドです。対話用のchatは全画面のTUIを開きます。

grafana-assistant prompt "assistantサービスのエラー率を見せて" --json
grafana-assistant prompt "ハンドラ別に分けて" -c <contextId> --json

落とし穴は、promptを呼ぶたびに新しい独立した会話が始まることです。文脈を引き継ぐには、最初の呼び出しに--jsonを付けてcontextIdを控え、以降の呼び出しに-c <contextId>を渡します。JSON出力は次の形です。

{
  "taskId": "a2a-xxx",
  "contextId": "uuid",
  "agentId": "grafana_assistant_cli",
  "status": "completed",
  "response": "アシスタントの全文回答"
}

statusはcompleted・failed・timeout・canceled・unknownのいずれかです。スキルは、文脈の引き継ぎが「context was not created by CLI」のように失敗したら、それまでの発見をプロンプト本文に直接書くよう案内しています。長い調査ほど、contextIdに頼るより要点を埋め込むほうが確実だという注記もあります。

応答時間は、アシスタントが呼ぶツールの数によって30秒から300秒ほどかかります。chatのタイムアウト既定は300秒で、--timeout 600で延ばせます。

CLIのアシスタントは読み取り専用

スキルによると、CLI側のGrafana Assistantは読み取り専用です。できることは次のとおりです。

  • PromQL・Graphite・LogQL・TraceQL・SQLなどで、設定済みのデータソースを横断して問い合わせる
  • データソース、メトリクス名、ラベル値、ログストリームを探す
  • ダッシュボードを検索し、パネル定義を読む
  • Grafanaのドキュメントやブログを検索する
  • アラート履歴、オンコール、インシデントを調べる

逆に、ダッシュボードの作成・変更、アラートルールとサイレンスの管理、Grafana画面への誘導は、CLIでは使えません(Web版とSlack版だけ)。変更まで任せたい場合は、grafana-cloud-mcpの書き込み権限つきの接続のほうが向きます。書き込みの認可には、Assistant Adminロールかgrafana-assistant-app.cloud-mcp.scope:write権限が別途要ります。

調査の流れは、スキルが3つの型で説明しています。

型流れ
素早いデータ確認流れデータソースを探す、メトリクスやログ名を探す、クエリを実行、結果を提示
障害調査流れメトリクスからログ、トレースへ信号を追い、原因を絞る
Q&A流れGrafanaや可観測性の質問をドキュメントで答える

ルールファイルはClaude Codeでどう効くか

ここがこのプラグインで最も読み違えやすい点です。同梱のルールはrules/grafana-assistant.mdc、つまりCursorのルール形式です。READMEの1行目も「Cursor plugin」と書かれています。

一方、Claude Codeのプラグインの標準レイアウト表に並ぶのは、スキル・コマンド・エージェント・フック・MCPサーバー・LSPサーバーなどで、rules/ディレクトリは載っていません。したがって、.mdcがClaude Codeで自動的に読み込まれるとは言えません。確実に効くのはスキル側です。

ルールの中身は、Grafana MCPのツールを前提にした8項目です。

  • get_dashboard_by_uidではなくget_dashboard_summaryを使い、完全なJSONでコンテキストを埋めない
  • get_dashboard_propertyでJSONPathを使い、必要な部分だけ取る
  • 部分的な変更にはpatch_dashboardを優先する
  • Prometheusには妥当な時間範囲を指定する
  • Lokiにはラベルマッチャーつきの絞ったLogQLを使う
  • 取得の前にsearch_dashboardsで探す
  • 書き込み系(update_dashboard・create_incident・create_alert_rule)は、ユーザーが明示したときだけ
  • 結果を示すときはgenerate_deeplinkでクリックできるURLを付ける

READMEによれば、これらのMCPツールを使うにはgrafana-mcpプラグインを別に入れます。grafana-assistantだけを入れた状態では、ルールの指すツールがそもそも存在しません。

ルールをCLAUDE.mdに写して使う

MCPも併用するなら、この8項目をCLAUDE.mdに書き写すのが確実です。例えば次のような形です(公式のルールに沿った例示です)。

## Grafana MCP の使い方
- ダッシュボードは get_dashboard_summary で概要を見てから、
  get_dashboard_property で必要な部分だけ取得する
- Prometheus のクエリには必ず時間範囲を付ける
- update_dashboard / create_incident / create_alert_rule は、
  ユーザーが明示的に頼んだときだけ実行する

ツール名の違いにも注意が要ります。ルールは部分変更にpatch_dashboardを挙げますが、mcp-grafanaのダッシュボード解説では、部分変更はupdate_dashboardのpatchモードとして扱われています。実際に使えるツール名は、入れたMCPサーバーのツール一覧で確かめてから写してください。ダッシュボードの読み方はsummaryとJSONPathの使い分けに詳しくあります。

実行権限とセキュリティ

スキルには「Shellツールではrequired_permissions: ["all"]を使う」「block_until_msを300000以上にする」という指示があります。どちらもCursorのShellツールの引数名です。Claude Codeでは対応する設定が別なので、そのまま真似せず、権限はsettings.jsonのpermissionsで決めます。

grafana-assistantだけを事前に許可する例を挙げます。

{
  "permissions": {
    "allow": ["Bash(grafana-assistant prompt *)"]
  }
}

promptは読み取り専用のアシスタントに質問を送るだけですが、tunnel系は別です。トンネルは、Grafana Assistantに自分のマシン上でツールを実行させる仕組みで、tunnel connectはフォアグラウンド接続、--terminalでターミナルツールを有効にします。既定の保護は次のとおりです。

  • ファイルシステム: 読み取り専用で、プロジェクトの範囲に限る。~/.ssh・~/.gnupg・~/.aws/credentials・**/.env・**/secrets.yaml・**/*.pem・**/*.keyを遮断し、ファイルサイズの上限は1MB
  • ターミナル: rm -rf /・mkfs・dd・フォーク爆弾などを遮断し、環境変数は最小限

許可と拒否の一覧は、設定ファイルのtunnel.toolsで変えられます。tunnel系を許可に含めるかどうかは、allowに入れる範囲で線を引きます。

よくあるつまずき

  • プラグインを入れたのにデータが見えない: MCPサーバーが同梱されていないためです。Grafanaのデータを直接読むならgrafana-cloud-mcpかgrafana-mcpを足します。
  • grafana-assistant: command not found: スキルは自動導入をしません。assistant-cliのバイナリを$PATHに置きます。
  • 追加質問の答えが前の話を覚えていない: --jsonと-c <contextId>を使っていない可能性が高いです。
  • ブラウザ認証が通らない: Assistant CLI Userロールかgrafana-assistant-app.tokens:access権限が足りません。
  • ダッシュボードを書き換えさせたい: CLIのアシスタントは読み取り専用です。

同じようにスキルと周辺ツールを束ねた可観測性系のプラグインには、Claude CodeのLogfireプラグインがあります。プラグイン内の環境変数やパスの解決はプラグインの環境変数とパスの解決ルールにまとめています。

まとめ

このプラグインは、grafana-assistant CLIを使う人のための、スキル中心の薄い手引きです。Grafanaのデータへ直接つなぐ役目は、grafana-cloud-mcpかgrafana-mcpが担います。

CLIだけ先に動かしたいなら、CLIの導入とブラウザ認証、プラグインの導入の順です。ルールの8項目を生かしたいなら、MCPを併用したうえでCLAUDE.mdに写すほうが、Claude Codeでは確実です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →