prom-mcp

prom-mcp — AI エージェント（Claude Code、Cursor）向け Prometheus MCP サーバー

prom-mcp は、AI エージェントに本番環境のメトリクスを把握するための高品質な機能を提供する、Prometheus MCP サーバー（Model Context Protocol）です。 Claude Code、Cursor、または任意の MCP クライアントを Prometheus に接続すると、エージェントは PromQL クエリを実行し、発火中のアラートをルール定義とともに説明し、クエリの前に実際に存在する系列を検出できます。推測ではなく、調査を行えるようになります。

オンコール対応を担う本番環境のエンジニアが開発しているため、出力は生の JSON ダンプではなく、トリアージの記録のように読めます。

5 つのツール • 2 つのリソース • 1 つのトリアージ用プロンプト • Go の単一バイナリ • 依存関係ゼロ • stdio

インストール

Claude Desktop（MCPB、ツールチェーン不要）

お使いのプラットフォーム用のバンドルをダウンロードし、開くか、Claude Desktop（Settings → Extensions）にドラッグしてください。Prometheus の URL を尋ねられます。デフォルトは http://localhost:9090 です。

プラットフォーム	MCPB バンドル
macOS（Apple silicon）	prom-mcp_v0.2.0_darwin_arm64.mcpb
macOS（Intel）	prom-mcp_v0.2.0_darwin_amd64.mcpb
Linux（x86_64）	prom-mcp_v0.2.0_linux_amd64.mcpb
Linux（arm64）	prom-mcp_v0.2.0_linux_arm64.mcpb

Claude Code

バイナリを PATH に配置した状態で（リリースをダウンロードするか、以下の go install を実行します）：

claude mcp add prom -- prom-mcp

Prometheus の URL が http://localhost:9090 でない場合は、先にシェルで PROM_URL を設定するか、コマンドに --env PROM_URL=... を渡してください。その他の方法については、examples/claude-code.md を参照してください。

Cursor

~/.cursor/mcp.json に追加します（examples/cursor-mcp.json と同じファイルです）：

{
  "mcpServers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

VS Code

.vscode/mcp.json に追加します（examples/vscode-mcp.json と同じファイルです）：

{
  "servers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

Go install／ソースからビルド

go install github.com/aniketatgithub/prom-mcp@latest

git clone https://github.com/aniketatgithub/prom-mcp && cd prom-mcp
go build -o prom-mcp ./cmd/prom-mcp

上記の MCPB バンドルとあわせて、4 つのプラットフォームすべてに対応する通常のバイナリもリリース v0.2.0から入手できます。

どんな質問ができますか？

質問	prom-mcp の動作
「NodeDown が発火しているのはなぜですか？」	prom_alerts_explain は、アクティブなアラートにルール式、グループ、for、ラベル、注釈を結び付けて返します。
「実際に存在するジョブとインスタンスは何ですか？」	prom_series_discover と prom_label_values は、クエリを作成する前に実際の系列とラベル値を一覧表示します。
「状況は悪化していますか？」	prom_query_range は、系列ごとに対象期間のポイント数、最初の値、最後の値、最小値、最大値を要約します。

動作を見る

アラートのトリアージ：ノードがダウンしているのはなぜですか？

クエリの前に、何が存在するかを検出します：

傾向を確認します：node1 の状況は悪化していますか？

使用イメージ

エージェントに 「ノードがダウンしているのはなぜですか？」 と尋ねると、アラートツールがトリアージ形式で回答します。

1 active alert(s)

[firing] NodeDown (since 2026-10-08T10:00:00Z, value 0)
  labels: {alertname="NodeDown", instance="node1:9100", job="node", severity="critical"}
  summary: Node node1:9100 is down
  description: Scrapes failing for 5m
  rule: up{job="node"} == 0
  group: node.rules
  for: 5m0s

さらに、アラートの確認、ディスカバリー、傾向のチェックを順番にエージェントに案内する、組み込みの triage プロンプトテンプレートもあります。

ツール

ツール	機能
prom_query	PromQL クエリを即座に実行し、ラベル付きの時系列と値をコンパクトに表示します。
prom_query_range	過去 N 分間の範囲クエリを実行し、系列ごとのポイント、最初の値、最後の値、最小値、最大値を表示します。
prom_alerts_explain	アクティブなアラートを、アラートルールの式、ルールグループ、for の継続時間、アノテーションと結び付けます。
prom_label_values	ラベルの実際の値を一覧表示します（必要に応じて範囲を指定）。これにより、エージェントは実際のジョブ名やインスタンス名を把握できます。
prom_series_discover	ラベルマッチャーに該当する系列が存在するかを確認し、エージェントが存在しないメトリクス名をでっち上げるのを防ぎます。

リソース：prometheus://alerts（説明付きアラート）、prometheus://config。プロンプト：triage。

サーバーなしで試す

prom-mcp demo        # fixture-backed self-test: query, alert explanation, series discovery
prom-mcp query 'up'  # one-shot CLI query against $PROM_URL

設定

設定	環境変数	設定ファイルのキー
Prometheus のベース URL	PROM_URL	base_url
ベアラートークン（認証で保護された Prometheus 用）	PROM_TOKEN	token
リクエストタイムアウト	PROM_TIMEOUT（例：30s）	timeout_seconds
設定ファイルのパス	PROM_CONFIG

設定ファイルは JSON 形式で、$PROM_CONFIG、./prom-mcp.json、~/.prom-mcp.json の順に検索されます。

{ "base_url": "https://prometheus.example.com", "token": "…", "timeout_seconds": 30 }

環境変数はファイルの設定より優先されます。設定がない場合、デフォルトで http://localhost:9090 が使用されます。

エージェントに API への生アクセスを与えるだけではだめですか？

エージェントは Prometheus の生の JSON に埋もれ、存在しないメトリクス名を作り出してしまいます。prom-mcp は簡潔でラベル付きのトリアージ形式のテキストを返し、クエリの前にディスカバリーを行うようエージェントを促します。これが、推測するエージェントと調査するエージェントの違いです。

Go の単一バイナリで、依存関係はなく、独自の Prometheus に対して完全にオフラインで動作します。

サーバーを比較していますか？pab1it0/prometheus-mcp-server および Prometheus 組織の prometheus/prometheus-mcp との率直な比較については、docs/comparison.md をご覧ください。

FAQ

prom-mcp はどの AI クライアントで動作しますか？ あらゆる MCP クライアントで動作します。Claude Code、Cursor、Windsurf、Zed、カスタムエージェントに対応しています。stdio 上で、改行区切りの JSON-RPC 2.0 を使用します。

prom-mcp をリモートの Prometheus に接続するにはどうすればよいですか？ サーバーを追加するときに、PROM_URL に Prometheus のベース URL（例：http://localhost:9090 または社内エンドポイント）を設定してください。

AI エージェントは、Prometheus アラートが発火している理由を説明できますか？ はい。prom_alerts_explain は、アクティブなアラートを、それを発火させたルール（式、概要、説明）と結び付けます。そのため、エージェントは生の JSON を報告するのではなく、原因を推論できます。

prom-mcp に API キーやクラウドサービスは必要ですか？ いいえ。ローカルの単一バイナリで、Prometheus とのみ通信します。

prom-mcp は他の Prometheus MCP サーバーとどう違いますか？ docs/comparison.md をご覧ください。要約すると、prom-mcp は5つのツールを備えた、アラートトリアージに特化した選択肢です。他のサーバーは、Prometheus API をより広範囲に扱うか、より多くのデプロイ用機能を提供します。

Prometheus HTTP API をエージェントに公開する方法とはどう違いますか？ API に直接アクセスすると、エージェント自身で解析しなければならない入れ子の JSON が返され、存在しないメトリクス名を作り出す原因にもなります。prom-mcp はラベル付きのコンパクトなテキストを生成し、アラートをそれを発火させたルールと結び付け、長い出力を制限し、クエリの前にディスカバリーを促します。また、一時的な障害時の再試行とベアラートークン認証にも対応しています。

リモートまたは認証で保護された Prometheus でも動作しますか？ はい。PROM_URL と PROM_TOKEN（または JSON 設定ファイル）を設定してください。「設定」をご覧ください。

どのバージョンの Prometheus に対応していますか？ 標準の HTTP API（/api/v1/query、query_range、alerts、rules、series、label/<name>/values）を公開するサーバーであれば、どのバージョンでも対応しています。

ライセンス

MIT。LICENSE をご覧ください。