# Prometheus MCP server

> Allows LLMs to interact with Prometheus instances to execute PromQL queries, analyze metrics, and manage monitoring configurations.

- Repository: https://github.com/prometheus/prometheus-mcp
- Page: https://hostedmcp.org/servers/prometheus/prometheus-mcp
- Official: yes
- Transport: stdio
- Stars: 142
- License: Apache-2.0
- Latest version: 0.19.0-rc.0

## Install

### Claude Code

```sh
claude mcp add prometheus-mcp -- docker run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "prometheus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "prometheus-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"prometheus-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/prom/prometheus-mcp:v0.19.0-rc.0"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "prometheus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add prometheus-mcp -- docker run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.prometheus-mcp]
command = "docker"
args = ["run", "-i", "--rm", "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"]
```

### Gemini CLI

```sh
gemini mcp add -s user prometheus-mcp docker -- run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "prometheus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PROMETHEUS_MCP_PROMETHEUS_URL` | no | no |  |

## Tools (30)

- `alertmanagers`: Get overview of Prometheus Alertmanager discovery (read-only)
- `build_info`: Get Prometheus build information (read-only)
- `clean_tombstones`: Removes the deleted data from disk and cleans up the existing tombstones. I/O- and CPU-intensive; prefer low-traffic periods and confirm with the user before calling.
- `config`: Get Prometheus configuration (read-only)
- `delete_series`: Deletes data for a selection of series in a time range. Both start_time and end_time are required to prevent accidental deletion of all data. Deletion creates tombstones; run clean_tombstones or wait for compaction to reclaim disk space. Confirm the time range and matchers with the user before calling.
- `docs_list`: List of Official Prometheus Documentation Files. (read-only)
- `docs_read`: Read the named markdown file containing official Prometheus documentation from the prometheus/docs repo (read-only)
- `docs_search`: Search the markdown files containing official Prometheus documentation from the prometheus/docs repo (read-only)
- `exemplar_query`: Execute an exemplar query against the Prometheus datasource to find trace exemplars associated with metric samples (read-only)
- `flags`: Get runtime flags (read-only)
- `healthy`: Management API endpoint that can be used to check Prometheus health. (read-only)
- `label_names`: Returns the unique label names present in the block in sorted order by given time range and matches (read-only)
- `label_values`: Performs a query for the values of the given label, time range and matches (read-only)
- `list_alerts`: List all active alerts (read-only)
- `list_rules`: List all alerting and recording rules that are loaded (read-only)
- `list_targets`: Get overview of Prometheus target discovery (read-only)
- `metric_metadata`: Returns metadata about metrics currently scraped by the metric name. (read-only)
- `query`: Execute an instant query against the Prometheus datasource, returning one value per series at a single point in time (read-only)
- `quit`: Management API endpoint that can be used to trigger a graceful shutdown of Prometheus. Only call this when the user explicitly requests a shutdown.
- `range_query`: Execute a range query against the Prometheus datasource, returning values over a time window; use for graphing and trend analysis (read-only)
- `ready`: Management API endpoint that can be used to check Prometheus is ready to serve traffic (i.e. respond to queries.) (read-only)
- `reload`: Management API endpoint that can be used to trigger a reload of the Prometheus configuration and rule files. Safe; applies changes without downtime.
- `runbooks_list`: List the runbooks embedded in this server: guided workflows (Agent Skills) for common Prometheus tasks - investigating error rates and alert spikes, finding top CPU/memory/disk consumers, troubleshooting missing metrics or empty query results, health-checking Prometheus, reducing high-cardinality metrics, reviewing and drafting recording and alerting rules, and tuning Prometheus configuration. Call this and read the matching runbook with runbooks_read before starting any of these tasks. (read-only)
- `runbooks_read`: Read the named runbook: a guided workflow (Agent Skill) for a common Prometheus task, expressed in terms of this server's tools. Follow its guidance when a user request matches a runbook's purpose; runbooks_list shows what is available. (read-only)
- `runtime_info`: Get Prometheus runtime information (read-only)
- `series`: Finds series by label matches (read-only)
- `snapshot`: creates a snapshot of all current data into snapshots/<datetime>-<rand> under the TSDB's data directory and returns the directory as response. Safe, but confirm with the user before calling.
- `targets_metadata`: Returns metadata about metrics currently scraped by the target (read-only)
- `tsdb_stats`: Get usage and cardinality statistics from the TSDB (read-only)
- `wal_replay_status`: Get current WAL replay status (read-only)

## FAQ

### Can I use this with other Prometheus compatible backends?

Yes, the server is designed to work with other Prometheus API compatible services like Thanos, Mimir, and Cortex.

### How can I reduce token usage when querying metrics?

You can use TOON encoding to convert JSON data to a more token-efficient format, or enable API response truncation to limit the amount of data sent to the LLM.
