mcp-grafanaでアラートルールを作成し通知経路を調べる手順

mcp-grafanaのAlertingカテゴリは、アラートルール・通知の経路・サイレンスを6つのツールに分けて公開しています。ルールの参照用がalerting_rules_read、作成・更新・削除用がalerting_rules_writeです。通知経路の参照はalerting_manage_routing、サイレンスは読み取りと書き込みで別ツールになります。

この記事では、これらをClaude Codeから使って「なぜ鳴らないのか」「どこに通知が飛ぶのか」を調べ、ルールを作り直すまでの流れを、権限の切り分けと合わせて説明します。mcp-grafana自体の導入とサービスアカウントの基本設計はmcp-grafanaの導入とRBAC設計にあるので、ここではAlertingに絞ります。

Alertingカテゴリの6つのツール

READMEのツール一覧では、Alertingカテゴリは次の6つです。いずれも1つのツールにoperation引数が付いていて、操作を切り替える形になっています。

alerting_rules_readのoperationはlist・get・versionsの3つです。書き込み側のalerting_rules_writeは、この3つにcreate・update・deleteを足した6つを受け付けます。ルール単位の指定はUID(rule_uid)で行います。

アラートルールの状態を調べる

調査の入口はalerting_rules_readのlistです。絞り込みに使える引数は次のとおりです。

• states: firing・pending・normal・recovering・nodata・errorから指定
• label_selectors: {severity="critical", team=~"backend.*"}のようなPrometheus形式。複数指定はAND条件
• folder_uid・rule_group: フォルダUIDとルールグループ名の完全一致
• rule_type: alertingかrecording
• limit_alerts: ルールごとに返すアラートインスタンス数。listでは0だとインスタンスを返しません

返すルール数の上限はrule_limitで、既定も最大も200件です。search_rule_nameやsearch_folderによる部分一致検索、ラベルのmatchersによるインスタンス絞り込みはGrafana 12.4以降が必要と、ツール定義に書かれています。古いGrafanaではfolder_uidとstates、label_selectorsで絞る形になります。

Claude Codeには、状況をそのまま渡すのが早いです。

severity=critical のアラートルールのうち、今 firing か error のものを
一覧にして。それぞれ最終評価時刻とフォルダも出して

一覧で目当てのルールが見つかったら、getにそのUIDを渡します。getは状態に加えて設定(クエリ・条件・ラベル・通知設定)まで返すので、「条件式が想定どおりか」「forの長さが短すぎないか」の確認に向きます。versionsはそのルールの変更履歴を返すため、「いつ誰が閾値を変えたか」を調べる場面で使えます。

Prometheus・Lokiのデータソース管理ルールも読める

listとgetにdatasource_uidを渡すと、Grafana管理のルールではなく、PrometheusまたはLokiデータソースが持つルールを読めます。省略するとGrafana管理のルールが対象です。

渡せるのはruler APIに対応したデータソースだけで、それ以外を渡すと「PrometheusとLokiのみ対応」という趣旨のエラーが返ります。データソース管理ルールのlistではサマリーに式(query)が入ります。Grafana管理ルールでは式が複数のクエリノードに分かれるため、式の全体を見るにはgetが必要です。

この違いを知らないと、「一覧のqueryが空だから設定が壊れている」と読み違えます。listの空欄はGrafana管理ルールでは正常です。

通知の経路をたどる

「アラートは鳴ったのに通知が来ない」という調査では、alerting_manage_routingを使います。READMEの説明では、通知ポリシー・コンタクトポイント・時間間隔の参照ができます。operationは5つです。

通知ポリシーのツリーを取ると、ラベルによる振り分けの規則と、グルーピング・待ち時間・繰り返し間隔が一度に見えます。ルール側のlabelsとこのツリーを突き合わせれば、「team=paymentsのアラートはどのレシーバーに行くのか」が追えます。

通知ポリシーを取得して、team=payments, severity=critical のアラートが
どのコンタクトポイントに届くか、ツリーをたどって説明して。
途中でミュートする時間間隔があれば、その時間帯も教えて

一覧と詳細で返す情報量が違う点にも注意してください。get_contact_pointsは一覧用のサマリーで、既定の返却数は100件です(limitで変更)。連携設定の中身まで見たいときはget_contact_pointで名前を指定します。ツール側の説明では、このツールはアラートルールの設定や状態を返さないと明記されています。ルールと経路は別のツールで見る必要があります。

外部Alertmanagerのレシーバーも見られる

get_contact_pointsにdatasource_uidを渡すと、Alertmanager互換のデータソースが持つレシーバーを一覧にできます。READMEは対象としてPrometheus Alertmanager・Mimir・Cortexを挙げています。省略するとGrafana管理のコンタクトポイントです。

外部のAlertmanagerも使っている環境では、Grafana管理の経路とデータソース側の経路が併存します。どちらの経路で通知しているルールかを先に確かめてから、ポリシーを読むと混乱しません。

ルールを作る・更新する・削除する

書き込みはalerting_rules_writeです。createに必要な引数は、タイトル・ルールグループ・フォルダUID・条件の識別子・クエリ配列(data)・no_data_state・exec_err_state・for・組織IDで、省略できません。dataには、データソースのクエリと、__expr__を指定する式(reduce・threshold・math・classic_conditions)を並べます。

例えばPrometheusの式に閾値を掛けるルールは、概念的には次の2要素です。ツール定義の例に沿った形で、実際の値はお使いの環境に合わせます。refIdとrelativeTimeRangeは省略すると位置から自動で割り当てられますが、conditionとexpressionが参照するので、ここではrefIdを明示しています。

{
  "operation": "create",
  "title": "HighErrorRate",
  "folder_uid": "alerts-folder",
  "rule_group": "api-slo",
  "condition": "B",
  "for": "5m",
  "data": [
    { "refId": "A", "datasourceUid": "prometheus-prod",
      "model": { "expr": "sum(rate(http_requests_total{code=~\"5..\"}[5m]))" } },
    { "refId": "B", "datasourceUid": "__expr__",
      "model": { "type": "threshold", "expression": "A",
        "conditions": [ { "evaluator": { "type": "gt", "params": [5] } } ] } }
  ]
}

実際には、no_data_state・exec_err_state・org_idなども必要です。Claude Codeには細部を自分で書かせず、「この式で、5分間続いたらfiringにするルールをalerts-folderに作って。無データ時の状態はNoDataにして」のように意図を渡すと、引数の組み立てはモデルが担います。

注意点が3つあります。

1. updateは丸ごと置き換えです。ツール説明に「変更箇所だけでなく必須フィールドをすべて取る」とあります。getで現在の設定を取得してから、変更を加えた全体を渡す手順を指示に含めてください。
2. disable_provenanceの既定はtrueです。このまま作ると、ルールはGrafana UIから編集できます。falseにするとprovenanceがapiとして記録され、UIからの編集がロックされます。IaCと混在させたくないルールだけを意図的に固定する使い方です。
3. deleteはUID指定でルールを消す操作です。確認の手順はツール側にないため、承認はクライアント側の権限設定で掛けます。

通知先を指定したルール

ルールにはnotification_settingsで、レシーバー(必須)・group_by・group_wait・group_interval・repeat_interval・ミュート時間間隔・有効時間間隔を持たせられます。通知ポリシーのツリーを使わず、ルール単位で直接コンタクトポイントを指すやり方です。ポリシー経由とルール直指定のどちらで運用しているかは、getの結果で確認できます。

サイレンスで一時的に黙らせる

メンテナンス時間中の通知を止めたいときは、サイレンスを使います。ルールを止めるのではなく、条件に合致するアラートの通知だけを抑える仕組みです。alerting_silences_readのlistは、rule_uid(__alert_rule_uid__ラベルに対応)やマッチャーでの絞り込みができます。

alerting_silences_writeのcreateには、マッチャー・開始時刻と終了時刻(RFC3339)・コメントが要ります。updateでは、保存済みのstarts_atを渡し直さないと新しいIDで作り直される点が、ツール説明に書かれています。deleteは削除ではなく失効の操作です。

payments-api のルール(UID: abc123)を、今夜 22:00〜23:00(JST)だけ
サイレンスして。コメントは「DBメンテ」にして

時刻はタイムゾーン付きで渡させるのが無難です。「22時」とだけ伝えると解釈が揺れます。

コンタクトポイントを新規に作る

alerting_routing_writeのcreate_contact_pointは、Grafana管理のコンタクトポイントを1件作ります。名前・統合の種別(email・slack・webhookなど)・種別ごとの設定をJSONで渡します。戻り値はUID・名前・種別だけで、設定値やシークレットは含まれません。

制限は2つです。外部Alertmanagerのレシーバーは作れません。既存のコンタクトポイントの更新・削除用の操作もありません(ツール定義上、operationはcreate_contact_pointのみ)。既存の設定を変えたいときは、Grafana UIか別の仕組みで行う前提になります。

通知先のSlack Webhook URLなどの秘匿値をチャットに貼らせる運用は避けたいところです。トークン類は環境変数やシークレット管理側に置き、Claudeへの指示は「どのチャンネル向けに作るか」までに留めるほうが安全です。

権限を3層に分ける

READMEのRBAC表で、Alertingの各ツールが要求する権限は次のとおりです。

ルールの権限はフォルダ単位に絞れますが、通知経路とサイレンスはグローバルです。ここから、運用の切り分け方が見えてきます。

• 調査専用: 読み取り系の3ツールに必要な権限だけを持つサービスアカウントを作り、--disable-writeで起動する。書き込み系3ツールは登録自体が外れます
• ルール管理まで: ルールの書き込み権限を、アラート専用フォルダ1つにスコープして付ける。通知経路は触らせない
• メンテ運用: サイレンスの書き込みだけを別のサービスアカウントに分ける

--disable-writeの対象は、READMEではalerting_rules_write・alerting_silences_write・alerting_routing_writeの3つと明記されています。Alertingカテゴリごと止めたいときは--disable-alertingです。

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

この設定は、Alertingカテゴリだけを読み取り専用で登録する例です。--enabled-toolsに渡すカテゴリ名の一覧と既定値は、導入の記事で扱っています。ルール管理も許す登録を別名(たとえばgrafana-alerts-rw)で追加し、普段は読み取り専用の登録だけを有効にしておくと、書き込みの出番を意識的に選べます。

調査から修正までを1回で通す流れ

「ルールが想定どおり鳴らない」という依頼の標準的な流れは、次の順です。

1. alerting_rules_readのlistで、対象ルールを状態とラベルで特定する
2. getで設定を読み、クエリ・for・no_data_stateを確認する。versionsで直近の変更を確認する
3. alerting_manage_routingでポリシーのツリーを取り、ルールのラベルがどのレシーバーに届くかを確認する
4. 原因がルール側なら、getの全体をもとにupdateを実行する。経路側ならUIでの修正案を提示させる
5. 一時的に黙らせるだけなら、サイレンスを作る

2と3を同じ指示に入れるのがコツです。「ルール側の問題か、経路側の問題かを分けて報告して。まだ何も変更しないで」と書けば、読み取りだけで診断結果が返ります。書き込みの権限を持たせた環境でも、最初の指示を診断までにしておけば、変更の承認は人間が判断できます。

OnCallのアラートグループやスケジュールの操作は、Grafana OnCallをClaudeで操作する記事にあります。アラートルールの側(ここまでの内容)と、発報後の対応(OnCall)で、使うカテゴリが別である点を押さえておくと設計しやすくなります。

よくあるつまずき

ルールが一覧に出ない。 rule_limitは最大200件です。大規模な環境ではfolder_uidかlabel_selectorsで絞り込んでください。datasource_uidを付け忘れて、データソース管理のルールを探していることもあります。

search_rule_nameが効かない。 部分一致検索はGrafana 12.4以降が前提です。README全体の要件はGrafana 9.0以降ですが、機能ごとにもっと新しいバージョンを求めるものがあります。

サービスアカウントで権限エラーになる。 ルール系はフォルダのスコープが必要です。folders:readのスコープが対象フォルダに及んでいるかを確認します。通知経路の参照にはdatasources:queryも含まれる点が、見落としやすい部分です。

書き込みツールが見えない。 --disable-writeで起動していると、3つの書き込みツールは登録されません。意図した状態です。

まとめ

Alertingカテゴリは、ルール・経路・サイレンスを「参照用と書き込み用」に分けた6ツール構成です。調査は読み取り3ツールで完結し、書き込みはルールの作成・更新・削除、サイレンス、コンタクトポイントの新規作成に限られます。通知ポリシーそのものの変更や、既存コンタクトポイントの更新は、このカテゴリのツールにありません。

運用では、読み取り専用の登録を標準にして、書き込みは範囲を絞った別登録に分ける構成が扱いやすいはずです。updateが丸ごと置き換えである点と、disable_provenanceの既定値だけ、指示文に含めておくと事故を避けられます。