<div align="center">
  <h1>Prometheus MCP</h1>
  <p><strong>Query Prometheus from the CLI or any MCP client</strong></p>
  <p>Discovery helpers, retries, caching, and an optional metrics exporter.</p>
  <p>
    <a href="https://crates.io/crates/prometheus-mcp"><img src="https://img.shields.io/crates/v/prometheus-mcp.svg" alt="Crates.io"></a>
    <a href="https://docs.rs/prometheus-mcp"><img src="https://img.shields.io/docsrs/prometheus-mcp" alt="Docs.rs"></a>
    <a href="https://github.com/brenoepics/prometheus-mcp/actions/workflows/release.yml"><img src="https://github.com/brenoepics/prometheus-mcp/actions/workflows/release.yml/badge.svg" alt="Release CI"></a>
    <a href="https://github.com/brenoepics/prometheus-mcp/releases"><img src="https://img.shields.io/github/v/release/brenoepics/prometheus-mcp" alt="GitHub release"></a>
    <a href="https://hub.docker.com/r/brenoepics/prometheus-mcp"><img src="https://img.shields.io/docker/pulls/brenoepics/prometheus-mcp" alt="Docker pulls"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
  </p>
</div>

---

<!-- Installation buttons -->

## Install

| Cursor | VS Code |
|:------:|:-------:|
| <a href="https://cursor.com/en/install-mcp?name=prometheus-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22brenoepics%2Fprometheus-mcp%3Alatest%22%2C%22--mcp%22%2C%22--prometheus-url%22%2C%22http%3A%2F%2Fhost.docker.internal%3A9090%22%5D%7D"><img alt="Install MCP Server" src="https://cursor.com/deeplink/mcp-install-light.svg"/></a> | <a href="https://insiders.vscode.dev/redirect/mcp/install?name=prometheus%20mcp%20server&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22brenoepics%2Fprometheus-mcp%3Alatest%22%2C%22--mcp%22%2C%22--prometheus-url%22%2C%22http%3A%2F%2Fhost.docker.internal%3A9090%22%5D%7D"><img alt="Install on VS Code" src="https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white"/></a> |

- 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):

```bash
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):

```bash
# 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):

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

Or build a Docker image locally:

```bash
docker build -t prometheus-mcp:latest .
```

Usage (CLI)
-----------

The CLI mirrors the tools exposed over MCP.

- Instant query

```bash
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

```bash
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

```bash
prometheus-mcp list-metrics
```

- Metric metadata

```bash
prometheus-mcp metadata --metric 'up'
```

- Series selectors (repeat --selector)

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

- Label values

```bash
prometheus-mcp label-values --label 'job'
```

MCP server (stdio)
------------------

Start the MCP server over stdio:

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

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

```bash
prometheus-mcp --mcp --metrics-exporter --metrics-port 9091
```

Running in Docker
-----------------

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

```bash
# 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:

```bash
# 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:

```bash
# 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:

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

- CLI flags:

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

- Docker with env vars:

```bash
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:

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

With host Prometheus and exporter (macOS/Windows):

```json
{
  "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:

```json
{
  "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:

```bash
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:

```bash
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