Prometheus MCP Server

Release CI

A minimal Model Context Protocol (MCP) server focused on reading from Prometheus. It exposes Prometheus discovery and query tools to MCP-compatible apps and includes a convenient CLI for local queries.

Highlights

Instant and range queries via Prometheus HTTP API
Discovery helpers: list metrics, get metadata, series selectors, label values
Optional internal metrics exporter at /metrics (disabled by default)
Works as a stdio MCP server or a one-off CLI

Container images

Images are published to both Docker Hub and GHCR:

Docker Hub: brenoepics/prometheus-mcp
GHCR: ghcr.io/brenoepics/prometheus-mcp

Quickstart

Pick your preferred install method.

From crates.io (installs the prometheus-mcp binary):

cargo install prometheus-mcp prometheus-mcp --help

Prebuilt binaries (GitHub Releases):
- Download the latest release for your OS/arch: https://github.com/brenoepics/prometheus-mcp/releases
Docker (pull from Docker Hub or GHCR):

# Docker Hub docker pull brenoepics/prometheus-mcp:latest # or GHCR docker pull ghcr.io/brenoepics/prometheus-mcp:latest # Run the MCP server against a local Prometheus (pick one image) docker run --rm -it brenoepics/prometheus-mcp:latest --mcp \ --prometheus-url http://host.docker.internal:9090

Installation

Build from source (Rust):

cargo build --release # binary at ./target/release/prometheus-mcp

Or build a Docker image locally:

docker build -t prometheus-mcp:latest .

Usage (CLI)

The CLI mirrors the tools exposed over MCP.

Instant query

prometheus-mcp query --query 'up' --prometheus-url http://localhost:9090 # optionally set an evaluation time prometheus-mcp query --query 'up' --time '2025-09-27T12:00:00Z'

Range query

prometheus-mcp range --query 'rate(http_requests_total[5m])' \ --start '2025-09-27T12:00:00Z' --end '2025-09-27T13:00:00Z' --step '30s'

List metric names

prometheus-mcp list-metrics

Metric metadata

prometheus-mcp metadata --metric 'up'

Series selectors (repeat --selector)

prometheus-mcp series --selector 'up' --selector 'node_cpu_seconds_total{mode="idle"}'

Label values

prometheus-mcp label-values --label 'job'

MCP server (stdio)

Start the MCP server over stdio:

prometheus-mcp --mcp --prometheus-url http://localhost:9090

Optional: enable internal metrics at /metrics (default off):

prometheus-mcp --mcp --metrics-exporter --metrics-port 9091

Running in Docker

Use the published image from Docker Hub (or GHCR alternative shown):

# Start the MCP server (macOS/Windows: host.docker.internal works; Linux see alternatives below) docker run --rm -it brenoepics/prometheus-mcp:latest --mcp \ --prometheus-url http://host.docker.internal:9090

Linux alternatives when Prometheus runs on the host:

# Use host networking (Linux only) docker run --rm -it --network host brenoepics/prometheus-mcp:latest --mcp \ --prometheus-url http://localhost:9090 # Without host network: map host gateway and use host.docker.internal docker run --rm -it --add-host=host.docker.internal:host-gateway \ brenoepics/prometheus-mcp:latest --mcp \ --prometheus-url http://host.docker.internal:9090

One-off CLI in the container:

# Instant query docker run --rm brenoepics/prometheus-mcp:latest query --query 'up' \ --prometheus-url http://host.docker.internal:9090 # Range query docker run --rm brenoepics/prometheus-mcp:latest range --query 'rate(http_requests_total[5m])' \ --start '2025-09-27T12:00:00Z' --end '2025-09-27T13:00:00Z' --step '30s' \ --prometheus-url http://host.docker.internal:9090

Basic Auth

Pass credentials via environment variables or CLI flags.

Environment variables:

export PROMETHEUS_URL=https://prom.example.com export PROMETHEUS_USERNAME=api export PROMETHEUS_PASSWORD=secret prometheus-mcp --mcp

CLI flags:

prometheus-mcp --mcp \ --prometheus-url https://prom.example.com \ --prometheus-username api \ --prometheus-password secret

Docker with env vars:

docker run --rm -it \ -e PROMETHEUS_URL=https://prom.example.com \ -e PROMETHEUS_USERNAME=api \ -e PROMETHEUS_PASSWORD=secret \ brenoepics/prometheus-mcp:latest --mcp

Configuration

All settings can be provided via environment variables; some also via flags.

Name	Type	Default	CLI flag	Description
PROMETHEUS_URL	string (URL)	http://localhost:9090	--prometheus-url	Base URL of your Prometheus server
PROMETHEUS_TIMEOUT	integer (seconds)	10	—	HTTP request timeout
PROMETHEUS_RETRIES	integer	3	—	Number of retries for Prometheus API calls
PROMETHEUS_RETRY_BACKOFF_MS	integer (ms)	500	—	Time to wait between retries
PROMETHEUS_MIN_INTERVAL_MS	integer (ms)	—	—	Minimum interval between query requests (basic rate limit)
PROMETHEUS_CACHE_TTL_SECS	integer (seconds)	—	—	TTL for simple in-process caches (list metrics and label values)
PROMETHEUS_USERNAME	string	—	--prometheus-username	Basic auth username
PROMETHEUS_PASSWORD	string	—	--prometheus-password	Basic auth password
—	boolean	false	--mcp	Start MCP server over stdio
—	boolean	false	--metrics-exporter	Enable internal Prometheus metrics at /metrics
—	integer (port)	9091	--metrics-port	Port for /metrics when exporter is enabled

See docs/configuration.md for notes and examples.

Accessing from Claude Desktop

Follow the official guide to locate claude_desktop_config.json: https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users

Minimal Docker-based entry:

{ "mcpServers": { "prometheus": { "command": "docker", "args": ["run", "--rm", "-i", "brenoepics/prometheus-mcp:latest"] } } }

With host Prometheus and exporter (macOS/Windows):

{ "mcpServers": { "prometheus": { "command": "docker", "args": [ "run", "--rm", "-i", "-p", "9091:9091", "brenoepics/prometheus-mcp:latest", "--mcp", "--prometheus-url", "http://host.docker.internal:9090", "--metrics-exporter", "--metrics-port", "9091" ] } } }

With Basic Auth via environment variables:

{ "mcpServers": { "prometheus": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "PROMETHEUS_URL=https://prom.example.com", "-e", "PROMETHEUS_USERNAME=api", "-e", "PROMETHEUS_PASSWORD=secret", "brenoepics/prometheus-mcp:latest", "--mcp" ] } } }

More examples: see docs/claude-desktop.md.

Debugging

Use the MCP Inspector to exercise the server interactively:

npx @modelcontextprotocol/inspector

Connect with transport "STDIO", command prometheus-mcp, and optional args --mcp --prometheus-url http://localhost:9090.

Logs are appended to /tmp/mcp.jsonl; tail it with:

tail -f /tmp/mcp.jsonl

Security Considerations

The server does not provide authentication itself; when running outside stdio, keep it on localhost.
Handle credentials via environment variables or your secret manager. Avoid committing secrets.

License

Apache-2.0

prometheus-rs