Claude Media
ClaudeとPrometheusの連携でPromQLを書かずにメトリクスを聞く
Claude CodeMCPClaude連携チュートリアル

ClaudeとPrometheusの連携でPromQLを書かずにメトリクスを聞く

Prometheus公式のMCPサーバーをClaude Codeに繋ぎ、PromQLを書かずに自然言語でメトリクス調査とアラート原因の特定を行う手順です。

読了目安 約11分

Claude Prometheus連携でPromQLを書かずにメトリクスを聞ける

Prometheusは公式のMCPサーバー(prometheus-mcp)をGitHub Organizationのprometheus配下で公開しています。Claude Codeに接続すると、PromQLを手で組み立てなくても「クエリが遅い原因を調べて」「このメトリクスの高カーディナリティなラベルは何か」といった自然言語の質問がそのままメトリクス調査に変わります。

このMCPサーバーはPrometheusのHTTP APIをラップしたツール群として動き、クエリ実行・ラベル探索・ルール確認・公式ドキュメント検索までを1つの接続で扱えます。GitHub上はprometheus/prometheus-mcpとして公開されている一方、README記載のDockerイメージ名やバッジはtjhop/prometheus-mcp-server名義のまま残っています。

セットアップ前に確認すること

前提として、稼働中のPrometheusインスタンスにHTTP経由で到達できる環境が必要です。ローカル開発機のPrometheus(http://127.0.0.1:9090)でも、社内ネットワークの本番Prometheusでも接続先として指定できます。

インストール手段は3つあります。

手段向いている環境
バイナリ配布向いている環境ローカル検証・単発調査
Dockerイメージ(ghcr.io/tjhop/prometheus-mcp-server)向いている環境CI・使い捨て環境
Helm chart(Kubernetes)向いている環境クラスタ常駐・チーム共有
docker run --rm -i \
  ghcr.io/tjhop/prometheus-mcp-server:latest \
  --prometheus.url "https://your-prometheus:9090"

Dockerイメージ名はtjhop名義のまま残っていますが、prometheus/prometheus-mcpのREADMEが配布経路として案内しているイメージです。

Claude Codeへの接続設定

stdioトランスポートで動かす場合、Claude Code側のmcp.jsonにコマンドを登録します。HTTPトランスポートを選ぶと--web.listen-addressでポートを指定し、複数クライアントから同じサーバーに接続できます。

docker run --rm -p 8080:8080 \
  ghcr.io/tjhop/prometheus-mcp-server:latest \
  --prometheus.url "https://your-prometheus:9090" \
  --mcp.transport "http" \
  --web.listen-address ":8080"

社内で認証を挟んだPrometheusに繋ぐ場合は、--http.configにHTTP設定ファイルを渡すか、--web.config.fileでMCPサーバー自体をBasic認証・TLS背後に置けます。前者はPrometheus側への接続に使う認証情報の設定、後者はMCPサーバーへのアクセス自体を絞る設定です(詳細は後述のセキュリティ節)。

使えるツールは何があるか

ツールはPrometheusのHTTP API相当の機能をカバーしています。数が多いため、デフォルトでは全ツールが登録されますが、--mcp.toolsフラグで読み込むツールを絞り込めます。

カテゴリ代表的なツールできること
クエリ実行代表的なツールquery / range_queryできること瞬間値クエリ・時系列レンジクエリの実行
メタデータ探索代表的なツールlabel_names / label_values / seriesできることラベルの一覧・値・マッチするシリーズの検索
監視対象の把握代表的なツールlist_targets / list_rules / list_alertsできることターゲットdiscovery・ルール・アクティブなアラートの確認
構成・状態確認代表的なツールconfig / flags / runtime_info / build_infoできることPrometheus自体の設定・起動フラグ・ビルド情報の取得
統計代表的なツールtsdb_statsできることTSDBの使用量・カーディナリティ統計
ドキュメント検索代表的なツールdocs_list / docs_read / docs_searchできること公式Prometheusドキュメントの検索・参照
ガイド付き調査代表的なツールrunbooks_list / runbooks_readできることシステムヘルスチェックなど定型調査の手順読み込み

--mcp.tools=allが既定値で、coreを指定するとdocs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, seriesの最小セットだけが読み込まれます。コンテキストウィンドウの小さいクライアントで使う場合はこちらが有効です。コアセットに個別ツールを足すことも可能です。

prometheus-mcp-server \
  --mcp.tools=build_info \
  --mcp.tools=flags \
  --mcp.tools=runtime_info

このコマンドはcoreの11ツールにbuild_info flags runtime_infoを加えた14ツールだけを読み込みます。

Runbook機能で調査手順ごとClaudeに渡す

このMCPサーバーの独自性は、単発ツールだけでなく「Runbook」という調査手順そのものを埋め込んでいる点です。システムヘルスチェック、データ欠損のトリアージ、エラー率調査、高カーディナリティの最適化、記録・アラートルールのレビューといった定型タスクが、Agent Skill形式のガイド付きワークフローとして同梱されています。

Runbookは3つの経路で公開されます。

  1. ツール経由: runbooks_list / runbooks_read でモデルが自分でリストアップして読み込む。どのMCPクライアントでも動く最も汎用的な経路
  2. Skillリソース経由: skill://<name>/SKILL.md としてリソース公開。Skill対応ホストならローカルSkillと同じ扱いで読み込める
  3. MCPプロンプト経由: check-system-health のようなスキル名でMCPプロンプトとして登録され、スラッシュコマンド的に呼び出せる

固定手順を毎回指示する代わりに「システムの健康状態を確認して」と頼むだけで、モデルが該当Runbookを見つけて調査の切り口を提示する形です。

どんな質問が投げられるか

公式リポジトリのデモでは、次のような自然言語の依頼がそのままPrometheus調査に変換される例が紹介されています。

  • 「メトリクスのクエリが遅い。原因を調べて」→ 高カーディナリティなラベルの特定
  • 「MCPサーバー自身のメトリクスを見て、SLO用の記録ルールを提案して」→ prom_mcp_系メトリクスの分析とルール案の生成
  • 「Prometheusのメトリクス名・ラベル名の命名ベストプラクティスをまとめて」→ docs_search経由での公式ドキュメント要約
  • 「このPrometheusインスタンスの設定・フラグ・ビルド情報・稼働状況をまとめて確認して」→ config / flags / runtime_info / list_targetsを横断したレポート

いずれもPromQLの構文を意識せず、調べたいことをそのまま書く形になっています。

トークン消費を抑える2つの機能

Prometheusのクエリ結果は数千行のJSONになることがあり、そのままLLMに渡すとコンテキストを圧迫します。このMCPサーバーは2つの緩和策を用意しています。

TOON(Token-Oriented Object Notation)出力: --mcp.enable-toon-outputフラグでJSONの代わりにTOON形式へ変換して返せます。均一な配列データで効果が出やすい形式で、非均一な複雑オブジェクトではJSONのほうが効率的な場合もあると明記されています。効果はクエリのパターンに依存するため、実際のワークフローで比較するのが確実です。

API応答の切り詰め: --prometheus.truncation-limitで、Prometheus APIから返す行数・件数の上限を設定できます。既定は0(切り詰めなし)。対応ツールでは、この上限をツール呼び出し単位で上書きすることも可能です。

セキュリティ: 認証情報の転送に関する注意

HTTPトランスポートで動かす場合、MCPリクエストに付いたAuthorizationヘッダーはそのままPrometheusへのAPI呼び出しに転送されます。サーバー側はこの認証情報を検証しません。つまりMCPエンドポイントに到達できる相手は、既定クライアントの権限で最低限Prometheusをクエリできてしまうため、--web.config.fileによるBasic認証やネットワーク制御でエンドポイント自体を絞ることが前提になります。到達経路を閉域網や信頼済みネットワークに限定できるならTLS設定のみで足りますが、外部からの到達を完全には防げない環境では、資格情報転送の副作用を理解したうえでbasic_auth_usersを併用するかどうかを判断する必要があります。

よくあるつまずき

  • Dockerイメージ名がPrometheus公式orgと一致しない: GitHub上のリポジトリはprometheus/prometheus-mcpですが、README記載の配布イメージはghcr.io/tjhop/prometheus-mcp-server名義のままです。別プロジェクトと誤認しやすいので注意してください
  • TSDB管理系ツールが動かない: delete_seriesやsnapshotを呼んでもエラーになる場合、起動フラグに--dangerous.enable-tsdb-admin-toolsが付いているか確認してください
  • Thanos環境でconfigツールが404を返す: Thanosは集中管理された設定を持たないため未実装のエンドポイントです。バグではなくバックエンドの仕様差です
  • --mcp.toolsを絞らずコンテキストが膨張する: 既定のallは便利ですが、小さいコンテキストウィンドウのクライアントではcoreセットから始めて必要なツールだけ追加するほうが安定します
  • coreからどこまで広げるか迷う: 実際に投げる質問が構成確認(config flags runtime_info)や統計調査(tsdb_stats)を含むかを先に洗い出し、使う質問に対応するツールだけをcoreへ個別追加すると、コンテキストを抑えたまま必要な機能を確保できます

Prometheus互換バックエンドでの違い

ThanosやMimir、CortexのようなPrometheus互換バックエンドに接続する場合、--prometheus.backendフラグでツールセットを調整できます。

バックエンド主な違い
prometheus(既定)主な違い標準のPrometheusツール一式。--mcp.tools=allと機能的に同等
thanos主な違い集中管理された設定を持たないためconfigツールが無効。代わりにlist_storesでStore APIサーバー一覧を取得できる

configやalertmanagersのようにバックエンドが実装していないエンドポイントを呼ぶと404が返るため、Thanos環境では自動的に該当ツールが除外される設計です。Mimir・Cortexはルール管理系の拡張エンドポイントを持つため、今後のバージョンで対応が広がる可能性があります。現時点では--prometheus.backendに個別の値を持たないため、Mimir・Cortexへ接続する場合も既定のprometheusのまま扱うことになり、バックエンド固有の未実装エンドポイントを叩いたときに同様の404が起きうる点は把握しておく必要があります。

メトリクス自体も公開される

MCPサーバー自身もPrometheus形式のメトリクスを/metrics(既定パス)で公開します。ツール呼び出しの失敗数・所要時間、Prometheus API呼び出しの失敗数・レイテンシーなどがprom_mcp_プレフィックスで取得でき、Grafana向けのダッシュボードJSONもリポジトリに同梱されています。MCP経由の調査自体がどれだけ使われ、どこで失敗しているかを可観測にできる作りです。

まとめ

prometheus/prometheus-mcpはPrometheus公式Organization配下で開発されているMCPサーバーで、PromQLクエリの生成・実行からドキュメント検索、定型調査のRunbookまでを1つの接続でカバーします。Claude Codeからはstdioかhttpトランスポートで接続でき、TSDB破壊的操作は明示フラグなしでは動きません。既に自然言語でのメトリクス調査を試したいチームは、まずローカルのPrometheusインスタンスへDockerイメージで繋いでみるのが手早い入り口です。

社内のインシデント対応をClaude経由で自動化する場合は、Kubernetes MCPサーバーやArgoCD MCPサーバーと組み合わせることで、デプロイからメトリクス調査までの流れを1つのセッションで扱えます。

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

関連する記事

Claude Code をもっと見る →