Skip to main content
Glama
mcp-prometheus

mcp-prometheus

by mgcrea

@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

/api/v1/targets

1.5 MB

totals, unhealthy pools, and the unhealthy targets with lastError (~2 KB)

/api/v1/query (up, 124 series)

9 labels repeated per series

shared labels once in common_labels, numeric values

/api/v1/query_range

[ts, "0.005732144858390525"] per point

one array per series on the step grid, rounded, plus min/max/avg/last

/api/v1/rules

200 KB

flat list, filterable by health/state/type/name

/api/v1/metadata

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

prometheus_auth_status

Which Prometheus answered (version, hostname, external labels, retention, admin API), or what to configure

no

prometheus_query

Instant PromQL query

no

prometheus_query_range

Range query on a step grid, with per-series stats; view=stats, sort=max to survey

no

prometheus_list_metrics

Find metrics by name or help text, with type and help

no

prometheus_describe_metric

Type, help, series count, and every label with its cardinality and examples

no

prometheus_list_labels

Label names, optionally on a selector

no

prometheus_list_label_values

Values of one label, optionally on a selector

no

prometheus_list_alerts

Firing and pending alerts, most severe first, with counts

no

prometheus_list_rules

Alerting and recording rules; health=err finds broken ones

no

prometheus_list_targets

Scrape health: totals, unhealthy pools and targets with their errors

no

prometheus_get_tsdb_status

Head-block cardinality: top metrics, labels, label pairs

no

prometheus_request

GET any /api/v1/* endpoint, cut at max_chars

no

prometheus_delete_series

Delete series (counts first, refuses past max_series, needs confirm)

yes

prometheus_clean_tombstones

Purge deleted data from disk (needs confirm)

yes

prometheus_reload_config

POST /-/reload

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

PROMETHEUS_URL

yes

Base URL, including any path prefix (https://host/prometheus). No credentials in it.

PROMETHEUS_USERNAME / PROMETHEUS_PASSWORD

no

Basic auth for a proxy in front of Prometheus.

PROMETHEUS_TOKEN

no

Bearer token instead of basic auth.

PROMETHEUS_HEADERS

no

Extra headers as JSON, e.g. {"X-Scope-OrgID":"tenant-1"} for Mimir.

PROMETHEUS_ALLOW_WRITES

no

1 to register the admin tools.

PROMETHEUS_TIMEOUT

no

Query timeout, as seconds or a duration such as 60s (default 30).

PROMETHEUS_MAX_RETRIES

no

Retries for 429 and proxy 5xx (default 2). Query timeouts are never retried.

PROMETHEUS_UI_LINKS

no

0 to drop the Prometheus UI link from query results.

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 build

Then 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 format

Publish

pnpm dlx release-it       # bump, commit, tag
git push --follow-tags    # CI publishes to npm + GHCR from the tag

License

MIT

Available Tools

12 tools
prometheus_auth_statusPrometheus: Auth StatusA
Read-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 MetricA
Read-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 StatusA
Read-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 AlertsA
Read-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 LabelsA
Read-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 ValuesA
Read-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 MetricsA
Read-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 RulesA
Read-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 TargetsA
Read-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: QueryA
Read-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 RangeA
Read-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: RequestA
Read-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

    A4.2/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Executes constrained, read-only Prometheus queries for instant metrics, active alerts, and target health, with bounded resource usage and audit records.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      14
      40 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      14
      38 npm
      MIT