Skip to main content
Glama
@mgcrea/mcp-grafana

@mgcrea/mcp-grafana

by mgcrea

Grafana: Query Loki

grafana_query_loki
Read-only

Run LogQL queries against a Loki datasource to retrieve log lines or time-series metrics with time ranges and limits for debugging and analysis.

Instructions

Run LogQL through a Loki datasource. A log query ({namespace="api"} |= "error") returns lines newest first, each with its time, level and the labels that differ between lines (the shared ones once, as common_labels), cut at max_line_chars. A metric query (sum by (app) (count_over_time({namespace="api"} |= "error" [5m]))) returns series on a step grid with stats. Always put a label matcher in the selector and keep the range short: Loki scans every line in it. To count, prefer a metric query over fetching lines.

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_loki"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoRange 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.
exprYesA LogQL query, e.g. `{namespace="ingress-nginx"} |= "error" | json | status >= 500`. grafana_list_labels lists the stream labels to select on.
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.
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 log lines, or series for a metric query (1-5000). Defaults to 50.
startNoRange 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.
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.
instantNoFor a metric query: evaluate once at `end` instead of over the range.
directionNobackward (default): the newest `limit` lines. forward: the oldest first.backward
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 first Loki datasource. 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 / end / 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."
    • changedInput schema / properties / start / 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."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by describing the actual return shape of both query modes (lines newest-first with time, level, and per-line vs common_labels, cut at max_line_chars; series on a step grid with stats). It also discloses the cost characteristic that range scans read every line, which is material to how an agent should call it.

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?

Three tight sentences front-load what the tool is and what each mode returns, then close with the cost caveat and the counting recommendation. The inline query examples are long but they replace what would otherwise be several abstract clauses, so they largely earn their space.

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?

With 13 parameters, three enums, and no output schema, the description carries the return-value burden itself and does so for both log and metric modes, which is the main gap to fill. It is slightly thin on error behavior and on how common_labels interacts with limit truncation, but nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented and the baseline is 3. The description confirms that max_line_chars truncates lines and that metric results land on a step grid, but it adds no per-parameter meaning beyond what the schema already says for start/end/step/limit/sort.

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?

"Run LogQL through a Loki datasource" gives a specific verb and resource, and the LogQL/Loki framing distinguishes it cleanly from the PromQL sibling grafana_query_prometheus. The follow-up contrast between a log query and a metric query pins down the two modes the tool serves.

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?

It gives concrete operating guidance: always include a label matcher in the selector, keep the range short because Loki scans every line, and use a metric query rather than fetching lines when counting. It lacks explicit routing to siblings (grafana_query_prometheus, grafana_list_datasources, grafana_list_labels) beyond a passing label-hint, so exclusions are weaker than the when-to-use advice.

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