prometheus-mcp

prometheus-mcp

Prometheus のメトリクスとオブザーバビリティのための MCP サーバーです。 Claude（または MCP に対応した任意のエージェント）に Prometheus インスタンスへの読み取りアクセスを許可すると、会話を離れることなく PromQL でメトリクスをクエリし、アクティブなアラートを調べ、スクレイプターゲットを確認できます。

Prometheus MCP がもう一つ必要な理由

既存の Prometheus 連携には、カスタムスクリプトや API の直接的な知識が必要です。このサーバーには次の特徴があります。

• 標準の Model Context Protocol を stdio で使用するため、Claude Desktop、Claude Code、Cursor、および任意の MCP クライアントで動作します。
• 読み取り専用です。5 つのツールすべてに readOnlyHint: true が設定されており、Prometheus のデータを変更するリスクはありません。
• 2 つのチャネルで出力を返します。プログラムでの利用向けの構造化 JSON（structuredContent）と、人が読みやすい表示向けの Markdown（content）です。
• 修正が必要な正確な環境変数名を示し、次の手順を提案する、具体的なエラーメッセージを表示します。
• Bearer トークン、HTTP Basic 認証、または認証なし（内部デプロイで一般的）に対応しています。

ツール

ツール	エンドポイント	説明
prometheus_list_metrics	GET /api/v1/label/__name__/values	任意の部分文字列フィルターを使ってメトリクス名をすべて一覧表示します（上限 500 件）
prometheus_query	GET /api/v1/query	即時 PromQL クエリを実行します
prometheus_query_range	GET /api/v1/query_range	時系列を返す PromQL 範囲クエリを実行します
prometheus_list_alerts	GET /api/v1/alerts	アクティブなアラートと保留中のアラートを一覧表示します
prometheus_list_targets	GET /api/v1/targets	ヘルス状態とジョブごとにスクレイプターゲットを一覧表示します

v4.0 の高度なアラート相関機能

バージョン 4.0 では、AI エージェントが本番環境のエラーを自律的に調査するための強力な新機能が導入されました。

インスタンスをまたいだアラート相関

• 複数の Prometheus インスタンスにまたがる関連アラートを自動的に特定します
• サービス識別子ごとにアラートをグループ化し、インシデントの範囲を把握します
• 方向性のある依存関係を推定し、連鎖するアラートのパターンを検出します

根本原因分析

• 季節性を自動調整したメトリクスの異常検出
• 症状から根本原因の候補まで依存関係チェーンをたどります
• アラートと最近のデプロイや設定変更を関連付ける変化点検出
• 証拠の強さと影響分析に基づいて根本原因の候補を順位付けします

依存関係のマッピングとヘルス

• トラフィック相関分析に基づいてサービス依存関係マップを動的に構築します
• サービス間の相互運用を示す、クラスタをまたいだ依存関係を可視化します
• 合成ヘルスプローブにより依存関係のレジリエンスを評価します
• 依存関係の脆弱性に基づいて負荷遮断を提案します

傾向分析とベンチマーク

• 繰り返し発生するアラートスケジュールの過去のパターンを認識します
• リソースの枯渇を予測するキャパシティ予測
• 解決時間を過去のデータと比較する MTTR ベンチマーク
• パターンの崩れを検知し、より優先度の高い通知を発行します

統合分析ツール

• v4.0 の全機能を組み合わせた新しい federation_analyze_alerts ツール
• AI エージェントでの利用に最適化された統一出力形式
• 1 回のツール呼び出しで包括的なインシデントコンテキストを提供します

インストール

pip install prometheus-mcp

または、インストールせずに直接実行できます。

uvx prometheus-mcp

設定

すべての設定は環境変数で行います。

変数	必須	デフォルト	説明
PROMETHEUS_URL	はい	—	Prometheus サーバーの URL（例：https://prometheus.example.com、末尾にスラッシュを付けないでください）
PROMETHEUS_TOKEN	いいえ	—	Bearer トークン（Basic 認証より優先されます）
PROMETHEUS_USERNAME	いいえ	—	HTTP Basic 認証のユーザー名
PROMETHEUS_PASSWORD	いいえ	—	HTTP Basic 認証のパスワード
PROMETHEUS_SSL_VERIFY	いいえ	true	自己署名証明書の場合は false に設定します

.env.example を .env にコピーし、値を入力してください。

Claude Desktop / Claude Code のセットアップ

MCP 設定（claude_desktop_config.json または .claude/mcp.json）に追加します。

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

または、uvx を使用します（インストール不要）。

{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp"],
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com"
      }
    }
  }
}

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

クエリの例

設定後、Claude に次のように尋ねてください。

• 「Prometheus には HTTP リクエストに関するどのようなメトリクスがありますか？」
• 「payment サービスの現在のリクエストレートはいくつですか？」
• 「過去 1 時間の CPU 使用率を 5 分間隔で表示してください」
• 「発火中のアラートはありますか？ 重大度はどのくらいですか？」
• 「現在ダウンしているスクレイプターゲットと、その理由を教えてください」
• 「稼働中の node-exporter インスタンスはいくつありますか？」

ツールの使用ガイド

prometheus_list_metrics

Prometheus が認識しているすべてのメトリクス名を返します。pattern を使用すると、部分文字列（大文字と小文字を区別しません）で絞り込めます。利用可能なメトリクスがわからない場合は、まずこちらを使用してください。出力は 500 件までで、切り捨てが発生した場合はその旨が示されます。

prometheus_query

瞬時の PromQL 式を実行し、現在の値を取得します。結果の型（vector/scalar/matrix/string）、サンプル数、および各サンプルのラベルと値を返します。

パラメーター：

• query（必須）— PromQL 式（例：up、rate(http_requests_total[5m])）
• time（任意）— RFC3339 または Unix タイムスタンプ。デフォルトは現在時刻です

prometheus_query_range

時間範囲を指定して PromQL 式を実行します。一致する各時系列について、タイムスタンプ付きの値を含む系列を 1 つずつ返します。全系列のデータポイント数は合計 5000 件までです。

パラメーター：

• query（必須）— PromQL 式
• start / end（必須）— RFC3339 または Unix タイムスタンプ
• step（必須）— 15s、1m、5m などの解像度

1 系列あたりのポイント数が 11,000 件を超えるステップは、Prometheus により拒否されます（HTTP 422）。この場合は、ステップを大きくするか、範囲を狭めてください。

注： Prometheus の range API は、ブランチやコミットによる絞り込みをサポートしていません。絞り込みには PromQL のラベルマッチャーのみを使用します。

prometheus_list_alerts

ラベル（alertname、severity など）、状態、有効化時刻、現在値とともに、アクティブまたは保留中のアラートをすべて返します。状態の概要（発火中と保留中の件数）も含まれます。

prometheus_list_targets

ジョブ名、インスタンスアドレス、ヘルス状態（up / down / unknown）、前回のスクレイプ所要時間（ミリ秒）、およびエラーメッセージ（ある場合）を含むスクレイプターゲットを返します。ジョブごとの概要も含まれます。state で絞り込めます。指定できる値は active（デフォルト）、dropped、any です。

パフォーマンス特性

• すべてのツールは、接続プーリングを使用する単一の永続的な requests.Session を使用します。
• Prometheus は通常内部サービスであるため、環境プロキシをバイパスするよう、セッションの trust_env = False が設定されています。
• リクエストは 30 秒後にタイムアウトします。
• prometheus_query_range は、全系列の合計出力を 5000 ポイントまでに制限します。長い時間範囲では、より大きなステップを使用してください。
• prometheus_list_metrics は、絞り込み後のメトリクスを最大 500 件返します。

開発

git clone https://github.com/mshegolev/prometheus-mcp
cd prometheus-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

API 仕様

このプロジェクトには、サーバーが公開するすべての MCP ツールを記述した OpenAPI 3.0 仕様が specs/ ディレクトリに含まれています。

仕様を検証するには：

python3 specs/validate_spec.py

自動化

このリポジトリには、リリースプロセスを効率化する自動化スクリプトと GitHub Actions ワークフローが含まれています。

スクリプト

• scripts/auto-commit-push.sh - リリースのトリガーを任意で指定して、変更を自動的にコミットし、プッシュします
• scripts/release.sh - パイプラインの確認、バージョンの更新、タグ付けを含む、リリース全体の自動化を行います

GitHub Actions ワークフロー

• post-push-check.yml - 各プッシュ後にテストパイプラインのステータスを監視し、コミットにコメントします
• auto-release.yml - バージョン（パッチ、マイナー、またはメジャー）を更新してリリースを作成する手動ワークフローです

自動リリースを実行するには：

1. GitHub の Actions タブに移動します
2. 「Auto Release」ワークフローを選択します
3. 希望するバージョン更新の種類を指定してワークフローを実行します

ライセンス

MIT — LICENSE を参照してください。