Skip to main content
Glama
@mgcrea/mcp-grafana

@mgcrea/mcp-grafana

by mgcrea

Grafana: Query Prometheus

grafana_query_prometheus
Read-only

Run PromQL queries against a Prometheus datasource in instant or range mode to retrieve values, time-series stats, and outlier rankings for Grafana analysis.

Instructions

Evaluate PromQL through a Prometheus datasource. mode=instant (default) gives the value at one time — the right mode for almost every question, with any window written into the expression (increase(x[24h])). mode=range gives the shape over time on a step grid with min/max/avg/last per series; use view=stats with sort=max to find outliers among many series. Labels shared by every series come back once as common_labels. Aggregate in the expression (sum by, topk) rather than fetching raw series.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "expr": "<expr>"
    },
    "name": "grafana_query_prometheus"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoRange end for mode=range: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now.
exprYesA PromQL expression, e.g. `sum by (namespace) (rate(container_cpu_usage_seconds_total[5m]))`. $__interval, $__rate_interval and $__range are filled in by Grafana.
modeNoinstant (default) or range.instant
sortNoOrder of time series, applied before `limit` cuts: labels keeps the datasource's order; max/avg/last rank highest first, so a cut keeps the biggest.labels
stepNoResolution, as a duration (30s, 5m, 1h). Defaults to a round step giving `points` points. Grafana never goes below the datasource's scrape interval.
timeNoEvaluation time for mode=instant: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now.
viewNoFor time series. values: stats (min/max/avg/last) plus one value per step on a shared grid given by start and step, null where there was no sample. stats: the stats only, about a tenth of the size — use it to survey many series before reading a few.values
limitNoMaximum series (1-2000). Defaults to 100. To see the largest, write topk() into the query.
startNoRange start for mode=range: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now-1h.
pointsNoTarget points per series (2-1000), from which the step is picked. Defaults to 60; a dashboard in a browser asks for ~1000, which is rarely worth the tokens.
precisionNoSignificant digits to round fractional values to (whole numbers are never rounded). Defaults to 4; 0 returns the exact value.
datasourceNoDatasource uid or name, e.g. "prometheus" or "Loki". Defaults to the default Prometheus datasource. grafana_list_datasources lists them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.2.0
    • changedInput schema / properties / end / description
      Previous value: -"Range end for mode=range: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now."New value: +"Range end for mode=range: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now."
    • changedInput schema / properties / start / description
      Previous value: -"Range start for mode=range: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now-1h."New value: +"Range start for mode=range: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now-1h."
    • changedInput schema / properties / time / description
      Previous value: -"Evaluation time for mode=instant: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now."New value: +"Evaluation time for mode=instant: now, now-1h, -30m, now/d or now-1d/d (rounded in UTC: a start to the start of the day, an end to its end), an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuine behavior beyond that -- default series limit of 100 with a topk tip, stats being 'about a tenth of the size', the scrape-interval floor on step, and that a browser dashboard asks for ~1000 points 'rarely worth the tokens'. It does not describe error modes or partial-result behavior, but the cost and size characteristics an agent needs are present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the verb and the mode default, then layers the secondary advice in decreasing priority. Every sentence carries an actionable rule or a return-shape fact; nothing is redundant or restated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter tool with no output schema, the description does the important compensating work: it characterizes the return payload (per-series min/max/avg/last, shared grid with nulls, common_labels) and explains the token-cost tradeoff between values and stats. A little more on how range errors or empty results appear would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds real semantics on top: what instant versus range return, why sort interacts with limit (a cut keeps the biggest), that $__interval/$__rate_interval are filled by Grafana, and that labels shared by every series come back once as common_labels. This goes beyond the schema's per-field documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Evaluate PromQL through a Prometheus datasource', which pins down both the query language and the backend. It implicitly separates itself from grafana_query_loki, but never names the sibling tools (grafana_query, grafana_run_panel_query) it could be confused with, so an agent must infer routing from the datasource wording alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance: mode=instant is 'the right mode for almost every question', range is for shape over time, and view=stats with sort=max locates outliers among many series. It also advises aggregating in the expression rather than fetching raw series. What it lacks is a negative rule at the tool level -- e.g. when to prefer grafana_query or a panel query instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.