Skip to main content
Glama
@mgcrea/mcp-grafana

@mgcrea/mcp-grafana

by mgcrea

Grafana: Query

grafana_query
Read-only

Run raw queries against any Grafana datasource via /api/ds/query—SQL, Elasticsearch, Tempo, CloudWatch—or evaluate server-side expressions over other queries.

Instructions

Run raw queries against any datasource through /api/ds/query — for datasources with no dedicated tool (SQL, Elasticsearch, Tempo, CloudWatch…), or for server-side expressions over other queries ({"datasource": "__expr__", "type": "math", "expression": "$A / $B"}). Each query is the target object as it appears in a panel's JSON (grafana_get_dashboard view=panel shows one). Prefer grafana_query_prometheus / grafana_query_loki for those two, and grafana_run_panel_query to reproduce a panel. Dashboard variables are NOT filled in here.

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": {
      "queries": "<queries>"
    },
    "name": "grafana_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoRange end: 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.
fromNoRange start: 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.
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
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, log lines or table rows per query (1-5000). Defaults to 100.
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.
queriesYesQuery objects, e.g. [{"refId": "A", "rawSql": "SELECT 1", "format": "table"}]. A query may carry its own "datasource" (uid string, or {"uid": ...}); refId defaults to A, B, C….
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 datasource, for queries that name none. grafana_list_datasources lists them.
max_line_charsNoCut each log line at this many characters (50-20000). Defaults to 1000.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.2.0
    • changedInput schema / properties / from / description
      Previous value: -"Range start: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now-1h."New value: +"Range start: 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 / to / description
      Previous value: -"Range end: now, now-1h, -30m, an RFC3339 timestamp (2026-01-31T12:00:00Z) or unix seconds/ms. Defaults to now."New value: +"Range end: 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.6/5.0
Behavior4/5

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

Annotations already cover the safe-read, open-world profile; the description adds behavioral facts not in them: dashboard variable substitution is not performed, view=stats is roughly a tenth the size of values, and the browser's ~1000 points is rarely worth tokens. It does not cover auth needs or error/partial-failure behavior, so not a 5.

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

Conciseness4/5

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

Four sentences, front-loaded with purpose and routing, and every clause carries information (siblings, expression example, variable caveat). The first sentence is long and packs the JSON example inline, which slightly hurts scannability but wastes no words.

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

Completeness5/5

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

For a 10-parameter, no-output-schema query tool this is complete enough: it identifies the datasource resolution default, how query objects are shaped, how many queries are allowed, output-size tradeoffs (view, limit, points, precision, max_line_chars), and the variable-substitution caveat an agent would otherwise trip on.

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 baseline is 3; the description still adds real meaning beyond it by explaining that each element of `queries` is the target object from a panel's JSON and by giving the __expr__ math example shape. It clarifies that sort is applied before limit cuts, which reinforces the schema text rather than merely repeating it.

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

Purpose5/5

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

States a specific verb and resource ("Run raw queries against any datasource through /api/ds/query") plus the exact scope condition: datasources with no dedicated tool, or __expr__ server-side expressions. It explicitly carves itself apart from grafana_query_prometheus, grafana_query_loki, grafana_run_panel_query, and grafana_get_dashboard, so an agent can route without opening schemas.

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

Usage Guidelines5/5

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

Names the preferred alternatives and the condition selecting them ("Prefer grafana_query_prometheus / grafana_query_loki for those two, and grafana_run_panel_query to reproduce a panel"), and gives a negative constraint: "Dashboard variables are NOT filled in here." That is explicit when-to-use, when-not, and where-else.

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