mcp-prometheus
This MCP server lets an agent efficiently query and inspect a Prometheus server, read-only by default, with optional admin tools only when writes are explicitly enabled.
Check which Prometheus is connected and whether it is configured, including auth mode, version, hostname, external labels, retention, and admin API status.
Run instant PromQL queries with limits, relative times, output rounding, and shared labels collapsed into
common_labels.Run range PromQL queries on a step grid with per-series min/max/avg/last stats, sorting, and compact values or stats views.
Discover metrics by name or help text, including type and help metadata.
Describe a metric's labels, cardinalities, examples, and series count before writing selectors.
List label names and label values, optionally filtered by selector and restricted to currently existing series.
Inspect firing and pending alerts, with counts, severity ordering, and search/filter options.
Inspect alerting and recording rules, including health, state, query text, and broken-rule errors.
Check scrape health: totals, unhealthy scrape pools, and failing targets with their errors.
Analyze TSDB head-block cardinality: top metrics, labels, and label pairs.
Make raw read-only GET requests to other
/api/v1/*endpoints via an escape-hatch tool.When
PROMETHEUS_ALLOW_WRITES=1, register admin tools to delete series, clean tombstones, and reload Prometheus configuration.
Provides tools for interacting with the Prometheus HTTP API, including instant and range PromQL queries, metric and label discovery, alert and rule inspection, scrape target health, TSDB cardinality status, and optional admin operations such as series deletion, tombstone cleanup, and configuration reload.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-prometheus show me firing alerts and any unhealthy scrape targets"
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.
@mgcrea/mcp-prometheus
A Model Context Protocol server for the Prometheus HTTP API: PromQL queries, metric and label discovery, alerts, rules, scrape health and cardinality, shaped to fit a context window.
The server is read-only by default. The admin tools are not merely refused when writes are off — they are never registered, so an agent cannot call them at all.
Why another one
Prometheus answers are built for dashboards, not for models. Measured on a kube-prometheus-stack install (~800k head series, 268 targets):
Endpoint | Raw | What this server returns |
| 1.5 MB | totals, unhealthy pools, and the unhealthy targets with |
| 9 labels repeated per series | shared labels once in |
|
| one array per series on the step grid, rounded, plus min/max/avg/last |
| 200 KB | flat list, filterable by health/state/type/name |
| 420 KB | searched by name and help text, cached |
It also does the things a model gets wrong on its own: relative times (now-1h), a round
step picked for ~60 points, label lookups limited to series that exist now rather than over
the whole retention, and PromQL errors returned verbatim with what to do about them.
Related MCP server: PMM MCP Server
Tools
Tool | What it does | Writes |
| Which Prometheus answered (version, hostname, external labels, retention, admin API), or what to configure | no |
| Instant PromQL query | no |
| Range query on a step grid, with per-series stats; | no |
| Find metrics by name or help text, with type and help | no |
| Type, help, series count, and every label with its cardinality and examples | no |
| Label names, optionally on a selector | no |
| Values of one label, optionally on a selector | no |
| Firing and pending alerts, most severe first, with counts | no |
| Alerting and recording rules; | no |
| Scrape health: totals, unhealthy pools and targets with their errors | no |
| Head-block cardinality: top metrics, labels, label pairs | no |
| GET any | no |
| Delete series (counts first, refuses past | yes |
| Purge deleted data from disk (needs | yes |
|
| yes |
There is deliberately no /-/quit and no TSDB snapshot tool (a snapshot copies the whole TSDB
onto a volume sized for one).
Configure
Variable | Required | Description |
| yes | Base URL, including any path prefix ( |
| no | Basic auth for a proxy in front of Prometheus. |
| no | Bearer token instead of basic auth. |
| no | Extra headers as JSON, e.g. |
| no |
|
| no | Query timeout, as seconds or a duration such as |
| no | Retries for 429 and proxy 5xx (default 2). Query timeouts are never retried. |
| no |
|
A self-signed certificate needs NODE_EXTRA_CA_CERTS=/path/to/ca.pem.
A configuration mistake — a malformed URL, a token and basic auth, invalid
PROMETHEUS_HEADERS — never stops the server from starting. It starts with only
prometheus_auth_status, which says what to fix. An unreadable tuning value
(PROMETHEUS_TIMEOUT=soon, PROMETHEUS_UI_LINKS=maybe) disables nothing: it falls back
to its default, and prometheus_auth_status and the startup log list it under warnings.
Which Prometheus is this?
kube-prometheus-stack names everything identically on every cluster, so a .mcp.json copied
between projects answers every query with plausible numbers from the wrong one. The server
prints the instance it reached on startup (stderr), and prometheus_auth_status returns the
URL, version, hostname and external labels. If you run several clusters, set a distinguishing
external label (prometheus.prometheusSpec.externalLabels.cluster in kube-prometheus-stack).
Quick start
pnpm install
pnpm buildThen copy .mcp.json.example to .mcp.json and fill it in.
Inspect the tools
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| PROMETHEUS_URL=http://localhost:9090 node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'Develop
pnpm dev # tsdown --watch
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm formatPublish
pnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tagLicense
MIT
Available Tools
12 toolsprometheus_auth_statusPrometheus: Auth StatusARead-only
Report which Prometheus this server talks to and whether it answers: the URL, auth mode, Prometheus version, hostname, external labels and retention, and whether the admin API is enabled. When the server is not configured, says exactly what to set. Call this first when a tool you expected is missing, and before trusting numbers from an instance you have not checked — kube-prometheus-stack installs look alike on every cluster, so the URL host is often the only tell.
Inputs: no named parameters.
prometheus_describe_metricPrometheus: Describe MetricARead-only
Everything needed to query one metric: type, help, unit, how many series it has, and each label with its number of distinct values and examples. Read this before writing a selector — it shows which labels exist to filter and group by, and whether a label is high-cardinality (pod, uid) and so a bad thing to group by.
Inputs: metric (required), end, start, examples.
prometheus_get_tsdb_statusPrometheus: Get TSDB StatusARead-only
Cardinality: how many series the head block holds, and which metrics, labels and label pairs account for most of them and of the memory. Use it to explain a slow or memory-hungry Prometheus, or before grouping by a label that might have thousands of values. Covers the head block only (the last ~2-3 hours), not the full retention.
Inputs: limit.
prometheus_list_alertsPrometheus: List AlertsARead-only
List the alerts Prometheus is currently firing or holding as pending, firing first and most severe first, with their labels, summary and description, plus counts by state and severity. This is Prometheus's own view: silences and inhibitions live in Alertmanager and are not applied here, so an alert listed here may not have paged anyone. An always-firing Watchdog alert is a heartbeat, not a problem.
Inputs: limit, state, search, severity.
prometheus_list_labelsPrometheus: List LabelsARead-only
List label names, across everything or only on series matching a selector. To see one metric's labels with their values, prometheus_describe_metric is more useful.
Inputs: end, match, start, search.
prometheus_list_label_valuesPrometheus: List Label ValuesARead-only
List the values one label takes — every namespace, job or instance — optionally only on series matching a selector (e.g. the pods of one deployment). Use it to get exact values right before filtering on them, instead of guessing at a regex.
Inputs: label (required), end, limit, match, +2 more.
prometheus_list_metricsPrometheus: List MetricsARead-only
Find metric names, with their type (counter, gauge, histogram, summary) and help text. search matches the name or the help text, so disk finds node_filesystem_avail_bytes by its description. Use this before writing a query against a metric you have not seen, then prometheus_describe_metric for its labels. Counters need rate() or increase(); summing a raw counter is the most common PromQL mistake.
Inputs: end, limit, match, start, +2 more.
prometheus_list_rulesPrometheus: List RulesARead-only
List alerting and recording rules with their PromQL, health and state. Use health=err to find rules that fail to evaluate (their lastError says why) — a broken alert rule never fires, which looks exactly like everything being fine. Use type=record to find a recording rule's name before querying it, since a precomputed series is far cheaper than recomputing it.
Inputs: type, group, limit, state, +3 more.
prometheus_list_targetsPrometheus: List TargetsARead-only
Scrape health: what Prometheus is failing to collect, and why. Always returns totals and every scrape pool with an unhealthy target; then lists targets, by default only the unhealthy ones with their lastError (a 404 is usually a wrong metrics path or port, a timeout a slow exporter, connection refused a pod not listening). A target that is down means its metrics stop — queries over it go quiet rather than erroring. Only active targets: the dropped ones (filtered out by relabeling) run to megabytes and are never fetched.
Inputs: limit, health, search, scrape_pool.
prometheus_queryPrometheus: QueryARead-only
Evaluate a PromQL expression at one instant — the current value of something, or a total/average over a window written into the expression (increase(x[24h]), avg_over_time(x[1h])). This is the right tool for almost every question; use prometheus_query_range only when the shape over time matters. Labels shared by every series are returned once as common_labels. Upstream order is kept, so sort_desc() and topk() rank the result; past limit the rest is cut and truncated is set.
Inputs: query (required), time, limit, precision.
prometheus_query_rangePrometheus: Query RangeARead-only
Evaluate a PromQL expression over a time range, for how something changed: a spike, a trend, when it started. Each series comes back with stats (min, max, avg, last) and, with view=values, one value per step on a shared grid given by start and step (null where there was no sample) — no per-point timestamps. The step is picked for about 60 points unless given. Many series are expensive: aggregate in the query (sum by), or use view=stats with sort=max to find the outliers first.
Inputs: query (required), end, sort, step, +4 more.
prometheus_requestPrometheus: RequestARead-only
Escape hatch: GET any /api/v1 endpoint the other tools do not wrap — /api/v1/query_exemplars, /api/v1/targets/metadata, /api/v1/alertmanagers, /api/v1/format_query, /api/v1/status/walreplay. The answer is the raw data of the envelope, unshaped, cut at max_chars. Read-only: only GET is ever sent. Prefer the named tools, which shape their output; this one can return megabytes.
Inputs: path (required), params, max_chars.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool maps to a distinct Prometheus resource or action, and descriptions explicitly cross-reference each other (e.g. query vs query_range, list_metrics vs describe_metric, list_labels vs describe_metric) to steer selection. The only mild overlaps are the metadata cluster (list_metrics/describe_metric/list_labels/list_label_values) and the catch-all prometheus_request, but each has stated guidance on when to prefer it.
All twelve tools share a prometheus_ prefix and snake_case, with a mostly verb_noun pattern (query_range, list_alerts, describe_metric, get_tsdb_status, list_label_values). A few drop the verb (query, request, auth_status), which is a minor but readable deviation.
Twelve tools is well within the ideal 3-15 range and each one covers a distinct slice of Prometheus's read API (query, metadata, alerts, rules, targets, TSDB, connectivity). Nothing feels padded or redundant.
Core read workflows are fully covered: instant and range queries, metric/label discovery, alerts, rules, scrape health, cardinality, and instance identity. Minor gaps remain (no dedicated /api/v1/series or exemplars wrapper, config/flags only partially surfaced via auth_status), but the prometheus_request escape hatch lets an agent reach them.
Maintenance
Related MCP Connectors
Read-only access to a Lumin project's logs, metrics, uptime checks, alerts and infrastructure.
Read-only access to your Infrly services, deploys, logs, metrics and billing.
Provides read access to your GKE and Kubernetes resources.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Related MCP Servers
- AlicenseCqualityDmaintenanceExecutes constrained, read-only Prometheus queries for instant metrics, active alerts, and target health, with bounded resource usage and audit records.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to Percona Monitoring and Management 2.x through PromQL metric queries and Query Analytics, so clients can list monitored databases, surface the slowest queries, inspect query details, and run validated SELECT queries against QAN's ClickHouse data. TLS verification, input validation, and Viewer-role tokens keep access strictly observational.32 PyPI3MIT
- AlicenseAqualityBmaintenanceEnables agents to explore dashboards and run their panel queries with template variables resolved, query Prometheus and Loki datasources, and read alerts, silences and annotations across Grafana's sources in a context-friendly, read-only-by-default form, with write tools available only when explicitly enabled.1440 npmMIT
- AlicenseAqualityBmaintenanceEnables read-only querying and exploration of Grafana Loki logs and LogQL metrics, including labels, fields, volume, stats, patterns, rules, and contextual log retrieval, with responses shaped for context windows.1438 npmMIT