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

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のまま残っています。アラートルール自体の作成とテストはClaude CodeでPrometheusのアラートルールを書き、promtoolで検証するで扱います。

Claude Codeにつなぐまでの3ステップ

必要なのは、HTTPで到達できる稼働中のPrometheusです。ローカルのhttp://127.0.0.1:9090でも、社内ネットワークの本番インスタンスでも構いません。

Claude Codeのv2.1.289で、一時ディレクトリにstdio方式を登録した結果です。

claude mcp add -s project prometheus -- docker run --rm -i \
  ghcr.io/tjhop/prometheus-mcp-server:latest \
  --prometheus.url http://host.docker.internal:9090

Added stdio MCP server prometheus with command: docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url http://host.docker.internal:9090 to project config
File modified: /tmp/demo/p1/.mcp.json

生成された.mcp.jsonは次の形です。--より後ろがそのままサーバー側の引数になるため、--prometheus.urlはClaude Codeのオプションと衝突しません。

{
  "mcpServers": {
    "prometheus": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/tjhop/prometheus-mcp-server:latest",
        "--prometheus.url",
        "http://host.docker.internal:9090"
      ],
      "env": {}
    }
  }
}

Dockerで動かすときの接続先URL

コンテナの中から見た127.0.0.1はコンテナ自身を指します。ホストで動くPrometheusに繋ぐなら、Docker Desktopではhost.docker.internalがホストの内部IPに解決されます。上の例はこの書き方です。

Prometheus自体がKubernetes上にあるときは、MCPサーバーも同じクラスタにHelm chartで置く選択肢があります。Helm chartはOCI artifactとして配布されます。

helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
  --version <version> \
  --set prometheus.url=http://prometheus:9090

URLの渡し方にはREADME内の食い違いがあります。Dockerの使用例は環境変数PROMETHEUS_MCP_SERVER_PROMETHEUS_URLですが、同じREADMEの--help出力が載せる環境変数名はPROMETHEUS_MCP_PROMETHEUS_URLです。どちらが効くかを前提にせず、フラグの--prometheus.urlで渡すと迷いません。

stdioとHTTPのどちらで動かすか

READMEによると、トランスポートはstdio(既定)かHTTPです。それぞれ向く場面が違います。

HTTPで動かすときのClaude Code側は、URLを指定する1行です。

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"
 
claude mcp add -s project --transport http prometheus http://localhost:8080/mcp

登録後の.mcp.jsonは"type": "http"と"url": "http://localhost:8080/mcp"だけの短い形になります。HTTPではPOSTだけが処理され、一部のクライアントが開く単独のGETストリームには405が返りますが、動作には影響しません。

既定で登録されるツールと、絞り込み方

ツールはPrometheusのHTTP APIに対応しています。既定ではすべて登録され、TSDB管理系だけが別フラグの対象です。

読み取り専用のつもりで入れる場合、表の最後から2行目に注意が要ります。reloadとquitは、Prometheus側でどちらも--web.enable-lifecycleを付けて起動したときだけ有効になるAPIに対応しています。そのフラグを付けた環境では、--mcp.toolsの既定値allのままだと、モデルが設定再読み込みや停止を呼べる状態になります。

--mcp.tools=coreを指定すると、docs_list docs_read docs_search runbooks_list runbooks_read query range_query metric_metadata label_names label_values seriesの11個だけが読み込まれます。core以外の値は「coreに足す許可リスト」として扱われます。

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

この指定は、coreの11個に3個を足した14個だけを読み込みます。投げたい質問が設定確認(config flags)や統計(tsdb_stats)に及ぶかを先に決め、必要な分だけ足す形です。READMEはこの絞り込みを、コンテキストウィンドウの小さいLLM向けの配慮として説明しています。

長いクエリ結果とClaude Codeの出力上限

Prometheusのレスポンスは数千行のJSONになりえます。Claude Code側にも、MCPツールの出力に対する上限があります。

サーバー側で絞る手段は2つあります。1つ目は--mcp.enable-toon-outputで、JSONの代わりにTOON(Token-Oriented Object Notation)形式で返します。均一なオブジェクトの配列で効きやすい形式です。複雑で不揃いなオブジェクトではJSONのほうが効率的な場合もあり、トークンが減る保証はありません。

2つ目は--prometheus.truncation-limitです。APIから返す行数・件数の上限で、既定は0(切り詰めなし)です。対応ツールでは、モデルが呼び出しごとにこの上限を上書きできます。上限を入れると返る行数が減るので、Claude Code側の警告閾値に近づきにくくなります。

Runbookで調査手順ごと渡す

このMCPサーバーは単発ツールに加えて、調査手順そのものを同梱しています。システムヘルスチェック、データ欠損のトリアージ、エラー率調査、高カーディナリティの最適化、記録・アラートルールのレビュー、設定とパフォーマンスの調整です。各RunbookはSKILL.mdを持つAgent Skillの形式で、手順を固定せず「どのツールをどう使うか」の方向づけと例のクエリを示します。

Claude Codeでは、MCPプロンプトが/mcp__サーバー名__プロンプト名の形で呼べます。サーバー名をprometheusで登録したなら/mcp__prometheus__check-system-healthです。サーバー名にA-Z a-z 0-9 _ -以外の文字を使うと_に置き換わるので、名前は英数字とハイフンにすると読み違えません。

依頼文の実例

READMEのデモは、次の英語の依頼文で動かしています。日本語でも書けますが、元の文面が手がかりになります。

• querying my metrics is slow, can you help me figure out why? — 高カーディナリティなラベルの特定に進む。Claudeで動かしたデモ
• use the tools from the prometheus mcp server to investigate the metrics from the mcp server and suggest prometheus recording rules for SLOs — prom_mcp_系メトリクスからSLO用の記録ルール案を作る
• summarize prometheus metric/label name best practices — docs_search経由で命名規約を要約する
• please provide a comprehensive review and summary of the prometheus server. に設定・フラグ・ビルド情報の確認を続けた依頼 — 稼働状況の総合レポート

1つ目は症状だけを書いた曖昧な依頼で、2つ目は「このサーバーのツールを使って」と手段まで指定した依頼です。同じREADMEの中に両方の書き方があります。

認証情報の転送とエンドポイントの保護

Prometheus側が認証付きの場合、MCPサーバーは--http.configでPrometheusのHTTP設定ファイルを読みます。ファイルが読めない、または不正なときは、認証なしの接続に落ちず起動時に終了します。

HTTPトランスポートでは、MCPリクエストのAuthorizationヘッダーがそのままPrometheusのAPI呼び出しに転送されます。サーバーはこの資格情報を検証しません。スキームの付いていない値はBearerトークンとして送られます。stdioと、ヘッダーなしのリクエストは、フラグで作った既定のクライアントを使います。

MCPエンドポイントに到達できる相手は、少なくとも既定クライアントの権限でPrometheusを引けます。そのため--web.config.fileのTLS・Basic認証か、ネットワーク制御で入口を絞る前提になります。

よくあるつまずき

• .mcp.jsonのサーバーが使えない: プロジェクトスコープで登録した直後は承認待ちです。claude mcp listの「Pending approval (run claude to approve)」が出ていれば、claudeを対話起動して承認します
• TSDB管理系ツールが動かない: delete_seriesやsnapshotがエラーになるなら、起動フラグに--dangerous.enable-tsdb-admin-toolsがあるかを見ます
• Thanos環境でconfigが404になる: Thanosは集中管理された設定を持たず、そのエンドポイントを実装していません。サーバーの不具合ではなく、バックエンドの仕様です。下の--prometheus.backendで対応します
• ツールが多すぎて重い: 既定のallは、TSDB管理系を除く27個を登録します。coreから始めて足す形にします

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

Thanosのような互換バックエンドでは、--prometheus.backendでツールセットを調整できます。READMEの--helpが挙げる値はprometheusとthanosです。

Thanosで除外されるのは、Thanosが実装していないエンドポイントと、Prometheus固有のTSDB管理系です。MimirとCortexはルール管理用の追加エンドポイントを持ちますが、専用の値も、追加エンドポイント用のツールも用意されていません。

サーバー自身のメトリクスとヘルス確認

MCPサーバーも、リッスンアドレス(既定は:8080)の/metricsでPrometheus形式のメトリクスを公開します。ツール呼び出しの失敗数と所要時間、Prometheus API呼び出しの失敗数と所要時間、ドキュメント自動更新の失敗数などがprom_mcp_で始まる名前で取れます。Grafana用のダッシュボードJSONもリポジトリのgrafana/にあります。

ヘルス確認用に/-/healthyと/-/readyもあります。/-/healthyはプロセスが生きている間は常に200、/-/readyはMCPトランスポートが立ち上がると200を返し、起動前と停止中は503です。Kubernetesのlivenessとreadinessのprobeにそのまま当てられます。

まとめ

prometheus/prometheus-mcpは、PromQLの実行、ドキュメント検索、Runbookによる定型調査を1つの接続に載せます。入れる前に決めるのは、stdioかHTTPか、--mcp.toolsでreloadやquitを外すか、認証情報の転送を許す範囲です。

インシデント対応をClaudeで進めるなら、Kubernetes MCPサーバーやArgoCD MCPサーバーと同じセッションに並べると、デプロイからメトリクスまでを続けて調べられます。