Which integrations are available for this server?

Provides tools for querying Prometheus metrics through instant and range queries, discovering metrics and metadata, retrieving series selectors and label values via the Prometheus HTTP API.

How do I use prometheus-rs?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@prometheus-rs show me the current status of all services with the query 'up'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

prometheus-rs by brenoepics

Install

Cursor	VS Code

On Linux, prefer --network host and http://localhost:9090 in your config.
Full instructions (prebuilt binaries, Cargo, Docker, Claude Desktop) in the docs: https://brenoepics.github.io/prometheus-mcp/installation

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