prometheus-mcp

PyPI version Python versions License: MIT Tests

Prometheusメトリクスおよび可観測性のためのMCPサーバー。 Claude（またはMCP対応エージェント）にPrometheusインスタンスへの読み取りアクセス権を付与します。会話を離れることなく、PromQLでメトリクスをクエリしたり、アクティブなアラートを調査したり、スクレイプターゲットを確認したりできます。

なぜ別のPrometheus MCPが必要なのか？

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

stdio経由で標準のModel Context Protocolを使用 — Claude Desktop、Claude Code、Cursor、およびあらゆるMCPクライアントで動作します。
読み取り専用: 5つのツールすべてにreadOnlyHint: trueが設定されており、Prometheusデータを変更するリスクはゼロです。
デュアルチャネル出力: プログラム利用向けの構造化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`	ヘルス状態とジョブごとにスクレイプターゲットを一覧表示

インストール

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リクエストに関するどのようなメトリクスがありますか？"
"決済サービスの現在のリクエストレートは？"
"過去1時間のCPU使用率を5分間隔で表示して"
"発火しているアラートはありますか？重大度は？"
"現在ダウンしているスクレイプターゲットはどれで、その理由は？"
"node-exporterのインスタンスはいくつ稼働していますか？"

ツール使用ガイド

`prometheus_list_metrics`

Prometheusが認識しているすべてのメトリクス名を返します。patternを使用して部分一致（大文字小文字を区別しない）でフィルタリングします。利用可能なメトリクスが不明な場合は、ここから始めてください。出力は500メトリクスに制限され、切り捨てのヒントが表示されます。

`prometheus_query`

インスタントPromQL式を実行し、現在の値を取得します。結果の型（ベクトル/スカラー/行列/文字列）、サンプル数、サンプルごとのラベルと値を返します。

パラメータ:

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

`prometheus_query_range`

時間枠を指定してPromQL式を実行します。一致する時系列ごとに、タイムスタンプ付きの値を含む系列を返します。すべての系列を合わせた合計データポイントは5000に制限されています。

パラメータ:

query (必須) — PromQL式
start / end (必須) — RFC3339またはUnixタイムスタンプ
step (必須) — 15s, 1m, 5mのような解像度

Prometheusは、系列ごとに11,000ポイントを超えるステップを拒否します（HTTP 422）。この場合は、ステップを増やすか、範囲を狭めてください。

注意: Prometheusの範囲APIはブランチやコミットによるフィルタリングをサポートしていません。フィルターは純粋にPromQLのラベルマッチャーで表現されます。

`prometheus_list_alerts`

ラベル（alertname、severityを含む）、状態、アクティベーション時間、現在の値を含む、すべてのアクティブ/保留中のアラートを返します。状態の概要（発火中 vs 保留中の数）が含まれます。

`prometheus_list_targets`

ジョブ名、インスタンスアドレス、ヘルス状態（up/down/unknown）、前回のスクレイプ時間（ミリ秒）、およびエラーメッセージを含むスクレイプターゲットを返します。ジョブごとの概要が含まれます。stateでフィルタリング可能: active（デフォルト）、dropped、またはany。

パフォーマンス特性

すべてのツールは、接続プーリングを備えた単一の永続的なrequests.Sessionを使用します。
セッションにはtrust_env = Falseが設定されており、環境プロキシをバイパスします（Prometheusは通常、内部サービスであるため）。
リクエストは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

ライセンス

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

mshegolev/prometheus-mcp