Guides on Grafana Labs

Query metrics with Prometheus

Mon, 12 Oct 2026 08:33:19 +0000

Query metrics with Prometheus

Use the Grafana MCP server so your AI assistant can run PromQL queries against a Prometheus datasource in Grafana. You can run instant or range queries and discover metric and label names and values.

What you’ll achieve

You ask your assistant to check a metric or run a PromQL expression; the assistant uses the server’s Prometheus tools to run the query and return results (or describe available metrics and labels).

Before you begin

The server set up and configured with access to Grafana.
A Prometheus datasource configured in Grafana. The service account must have datasources:query and scope for that datasource (for example, datasources:uid:<uid>).

Run a PromQL query

In your MCP client, ask the assistant to query Prometheus. For example, you might say “What is the current value of up for the Prometheus datasource?” or “Run this PromQL: rate(http_requests_total[5m]).” The assistant uses the server’s Prometheus query tool with the datasource UID and your time range. You can request instant queries (single value) or range queries (series over time).

Discover metrics and labels

Ask the assistant to list metric names, label names, or label values for a given selector. The server exposes tools that call the Prometheus API (metric metadata, label names, label values). Use these to explore what’s available before writing PromQL.

list_prometheus_metric_names defaults to 10 results per page. The product of page and limit must not exceed 10,000. If it does and you need to explore > 10,000 results, narrow the regex to get fewer results. For Prometheus-compatible backends, regex filtering and the fetch limit are sent to the datasource, which must support the limit parameter to bound the response. Cloud Monitoring continues to filter metric descriptors locally.

Response size limit

Prometheus API responses are limited to 10 MiB after decompression. Responses above this limit return an error instead of partial results. If a query exceeds the limit, select fewer series, shorten the time range, or increase the step for a range query. For metric and label discovery, narrow the filters or requested time range.

Next steps

Query logs with Loki for log and LogQL use cases.
Run a dashboard panel query to execute a panel’s query from the MCP server.

Query logs with Loki

Wed, 29 Jul 2026 17:47:59 +0200

Query logs with Loki

Use the Grafana MCP server so your AI assistant can run LogQL log and metric queries against a Loki datasource in Grafana. You can also list label names and values and retrieve log patterns.

What you’ll achieve

You ask your assistant to search logs or run a LogQL expression; the assistant uses the server’s Loki tools to run the query and return log lines or metric values. You can also explore labels and patterns.

Before you begin

The server set up and configured with access to Grafana.
A Loki datasource configured in Grafana. The service account must have datasources:query and scope for that datasource.

Run a LogQL query

In your MCP client, ask the assistant to query Loki. For example, “Show me recent error logs from the Loki datasource” or “Run this LogQL: {job="myapp"} |= "error".” The assistant uses the server’s Loki query tool with the datasource UID, time range, and limit. You can run log queries (streams of log lines) or metric queries (counts, rates, etc.).

Explore labels and patterns

Ask the assistant to list label names or label values for a selector, or to retrieve detected log patterns. These tools help you discover what’s in your logs before writing LogQL.

Next steps

Query metrics with Prometheus for PromQL use cases.
Search and inspect dashboards to find and explore dashboards.

Search and inspect dashboards

Tue, 20 Oct 2026 22:17:27 +0000

Search and inspect dashboards

Use the Grafana MCP server so your AI assistant can search for dashboards and inspect them (summaries, panel queries, or specific properties) without pulling full dashboard JSON. That keeps context window use under control.

What you’ll achieve

You ask your assistant to find dashboards or to summarize a dashboard, list its panels and queries, or extract specific fields. The assistant uses search, get summary, get panel queries, or get property tools as appropriate.

Before you begin

The server set up and configured with access to Grafana.
The service account must have dashboards:read and scope for the dashboards you care about.

Search for dashboards

Ask the assistant to search for dashboards by title, folder, tag, or starred status. The server’s search tool returns matching dashboards with metadata. Use this to find the UID or folder of the dashboard you want.

Get a dashboard summary or panel queries

When you need an overview of a dashboard without the full JSON, ask for a dashboard summary. You get title, panel count, panel types, variables, and similar metadata. To see what each panel queries, ask for panel queries: the assistant uses the tool that returns panel title, query string, and datasource UID and type for every panel.

To prepare panel query text, pass variables: {} to use saved selections, or provide explicit variable overrides. Optional start and end use the same frontend time macros as panel execution. Use absolute bounds when comparing separate calls. A referenced All selection returns a warning asking for an explicit value. Inspection reads the dashboard without querying variable options or looking up datasource types. Datasource plugin macros and visual targets retain their existing behavior.

Get specific properties with JSONPath

When you only need certain parts of a dashboard (for example, one panel’s config), ask the assistant to use get_dashboard_property with a JSONPath expression (for example, $.panels[0].title). That fetches only the requested data and avoids loading the full dashboard.

Inspect a previous dashboard version

To see how a dashboard looked at a previous save, first list its versions. The server returns compact metadata only (version number, author, timestamp, and save message), not the full JSON. Then ask for the dashboard by UID with that version number. Omitting version still returns the current dashboard.

Next steps

Generate deeplinks to Grafana to get shareable links to dashboards and panels.
Manage alert rules to create or update alert rules from your assistant.

Manage alert rules

Tue, 20 Oct 2026 07:22:51 +0000

Manage alert rules

Use the Grafana MCP server so your AI assistant can list and fetch alert rules, create or update rules, delete rules, and inspect notification policies and contact points.

What you’ll achieve

You ask your assistant to show firing alerts, add a new alert rule, change a rule’s condition or labels, or list contact points. The assistant uses the server’s alerting tools with the permissions you’ve granted.

Before you begin

The server set up and configured with access to Grafana.
The service account must have alert.rules:read (and alert.rules:write for create/update/delete) and appropriate folder scopes. For routing (contact points, policies), alert.notifications:read is required.

List and inspect alert rules

Ask the assistant to list alert rules or get details for a rule by UID. You can filter by folder or labels. The assistant uses the alerting tools to return rule title, state (firing, pending, normal), and configuration.

Create or update alert rules

Ask the assistant to create a new alert rule or update an existing one. You provide (or the assistant infers) the folder UID, condition, queries, labels, and annotations. The service account needs write permissions and scope for the folder. The assistant uses the server’s create/update alert rule tool.

Creation defaults to Grafana-managed. The assistant can select managed_by: "datasource" when the user requests it or when established conversation or environment context clearly identifies a datasource-managed workflow. For example, the user’s alerting setup may already be known to manage rules exclusively in a writable external backend. Using an external datasource in a query or finding no Grafana-managed rules alone does not establish that intent. If context conflicts, the assistant should ask before creating anything.

The assistant must still send managed_by: "datasource" in the tool call. Omitting it keeps Grafana-managed creation. The server does not infer a management target from datasource discovery or switch targets after an error.

Create a datasource-managed rule

alerting_rules_write supports creating alerting rules in Mimir/Cortex and Loki rulers. Standalone Prometheus does not support rule creation through this API. Enable rule management in the datasource configuration and configure the appropriate Prometheus type for Mimir/Cortex.

{
  "operation": "create",
  "managed_by": "datasource",
  "datasource_uid": "mimir-rules",
  "namespace": "pmo",
  "rule_group": "availability",
  "title": "ServiceDown",
  "expression": "up{job=\"pmo-service\"} == 0",
  "for": "5m",
  "labels": {"team": "pmo", "severity": "critical"}
}

An explicit datasource_uid takes priority and is validated. If omitted, the tool discovers compatible datasources visible to the caller. It selects one only when exactly one exists. With multiple candidates, it returns their names and UIDs so the assistant can ask the user to choose. With none, it returns an error. It never falls back to Grafana-managed creation.

The tool appends the rule to the existing group and preserves its other rules and settings. New groups default to a 1m evaluation interval. You can set evaluation_interval for a new group, but it must match the interval when adding to an existing group. If the existing group omits its interval and uses the ruler default, omit evaluation_interval to preserve it. Duplicate alert names in the same group are rejected. External creation uses expression and namespace, not Grafana-only fields such as data, condition or folder_uid. Update and delete remain Grafana-only.

For an explicitly selected Prometheus datasource without jsonData.prometheusType, the tool checks build information to select the Mimir or Cortex ruler route, then reads the group before writing. Automatic selection requires configured Mimir/Cortex metadata and does not probe every datasource.

Manage contact points and routing

Ask the assistant to list contact points or notification policies. The server exposes tools for Grafana-managed routing; for Alertmanager datasources, it can query receivers. Use this to see where alerts are sent or to describe routing before changing it (actual routing changes may require the Grafana UI or API outside MCP).

Create an external Alertmanager contact point

alerting_routing_write also defaults to Grafana-managed. Select managed_by: "datasource" when the user requests an external receiver or established context clearly identifies an external Alertmanager workflow. An external rule datasource or an empty Grafana contact point list alone is insufficient. Use a Mimir/Cortex Alertmanager datasource, which is selected independently from the rule datasource. Standalone Prometheus Alertmanager does not expose a writable configuration API.

{
  "operation": "create_contact_point",
  "managed_by": "datasource",
  "datasource_uid": "mimir-alertmanager",
  "name": "pmo-notifications",
  "type": "webhook",
  "settings": {"url": "https://example.com/alerts"}
}

The same optional UID selection rules apply independently to Alertmanager datasources. Use native Alertmanager settings, such as to for email, rather than Grafana’s addresses. disable_resolve_message controls resolved notifications. Grafana-only uid and disable_provenance are rejected for external creation.

The receiver is added without changing existing receivers, notification routes, templates, or other configuration fields in the request. A receiver name must be unique. An initial Alertmanager configuration with a root route must already exist. Creating a receiver does not connect it to a route or configure the ruler to send alerts to that Alertmanager. Configure those separately.

The result contains the receiver name, type and datasource UID, with an empty integration UID because external receivers are identified by name. It does not contain settings or secrets. If the API returns redacted secrets, the tool refuses to overwrite the configuration.

Permissions and concurrent writes

External rule creation requires datasources:read, alert.rules.external:read and alert.rules.external:write for the target datasource. External receiver creation requires datasources:read, alert.notifications.external:read and alert.notifications.external:write. The backend must also allow the write. Both creation paths remain disabled by --disable-write.

These APIs replace a complete rule group or Alertmanager configuration. The server serializes its own external creation calls for the same Grafana instance, datasource UID and destination group or Alertmanager configuration, regardless of organization selector. An implicit organization may be the same as an explicit one, so organizations that reuse the same destination identifiers conservatively share a lock. Other instances, datasources and rule groups can proceed independently, and unused locks are removed. This cannot prevent concurrent edits from other MCP processes, the Grafana UI, or other clients. Coordinate such writes to avoid overwriting concurrent changes. Unsupported APIs, permission errors and ambiguous destinations fail without creating anything in Grafana instead.

Next steps

Introduction for RBAC and permissions.
Search and inspect dashboards to find dashboards that use alerts.

Generate deeplinks to Grafana

Mon, 19 Oct 2026 10:16:42 +0000

Generate deeplinks to Grafana

Use the Grafana MCP server so your AI assistant can generate correct deeplink URLs to dashboards, panels, and Grafana Explore. The server uses the Grafana API to build URLs so you get working links instead of guessed paths.

What you’ll achieve

You ask your assistant for a link to a dashboard, a specific panel, or Explore with a given datasource (and optional time range). The assistant uses the server’s deeplink tool and returns a URL you can open or share.

Before you begin

The server set up and configured with access to Grafana.
No extra RBAC is required for generating links (read-only URL generation).

Get dashboard and panel links

Ask the assistant to generate a link to a dashboard by UID, or to a specific panel (dashboard UID and panel ID). You can request a time range (for example, last hour) so the link opens with that range. The assistant uses the server tool and returns a URL like http://localhost:3000/d/<uid>?viewPanel=<id>&from=now-1h&to=now.

Get Explore links

Ask for a link to Grafana Explore with a specific datasource (by UID). Optionally specify time range or other query parameters. The assistant returns a URL that opens Explore with that datasource and options pre-filled.

Shorten long links

Explore links can get long when they include encoded left state. Ask the assistant to call generate_deeplink with shorten=true. The server will try Grafana’s POST /api/short-urls endpoint and return a compact /goto/<uid> URL; if shortening is unavailable, it returns the full deeplink instead.

If you start the server with --disable-write, it ignores shorten=true and returns the full deeplink. Add --enable-write-tools=generate_deeplink to keep shortening.

Next steps

Search and inspect dashboards to find dashboard and panel IDs.
Query metrics with Prometheus or Query logs with Loki to work with datasources.

Run a dashboard panel query

Wed, 29 Jul 2026 17:47:59 +0200

Run a dashboard panel query

Use the Grafana MCP server to run a dashboard panel’s query (the same query the panel uses) with a custom time range and variable overrides. This is useful when you want the assistant to “run what this panel runs” without writing PromQL or LogQL yourself.

What you’ll achieve

You point the assistant at a dashboard and panel; the assistant uses the server’s run-panel-query tool to execute that panel’s query and return the result (or an error if the query or datasource is invalid).

Before you begin

The server set up and configured with access to Grafana.
The run-panel-query tool must be enabled (it’s disabled by default). Add runpanelquery to Enable and disable tools.
The service account must have dashboards:read and datasources:query with scope for the dashboard and the datasource the panel uses.

Run the panel query

Ask the assistant to run the query for a specific panel on a dashboard. Provide (or let the assistant look up) the dashboard UID and panel ID. You can specify a time range (for example, last 1 hour) and variable overrides so the query runs with the same logic as the panel but with your chosen parameters. The assistant calls the server’s run-panel-query tool and returns the result.

Next steps

Query metrics with Prometheus or Query logs with Loki to run custom PromQL or LogQL.
Search and inspect dashboards to find panel IDs and datasources.

Use Grafana Incident

Thu, 01 Oct 2026 13:22:11 +0000

Use Grafana Incident

Use the Grafana MCP server so your AI assistant can work with Grafana Incident (list, create, get, add activities, update). These features use Grafana basic roles: Viewer for read, Editor for write.

What you’ll achieve

You ask your assistant to list or create incidents, add a note to an incident, or update an incident’s status. The assistant uses the server’s Incident tools.

Before you begin

The server set up and configured with access to Grafana.
Grafana Incident available on your instance. The service account must have at least the Viewer role for read-only operations; Editor role for creating or updating incidents.

Work with incidents

Ask the assistant to list incidents (optionally filtered by status), get one incident by ID, create a new incident (title, severity, room prefix, etc.), or add an activity (note) to an incident. The assistant uses the server’s Incident tools. Creating incidents or adding activities requires Editor role.

Next steps

Introduction for roles and permissions.
Manage alert rules for alerting from the MCP server.

Query metrics with InfluxDB

Wed, 29 Jul 2026 17:47:59 +0200

Query metrics with InfluxDB

Use the Grafana MCP server so your AI assistant can run InfluxDB queries against an InfluxDB datasource in Grafana. The server supports both InfluxQL (v1.x) and Flux (v2.x); the dialect is inferred from the datasource’s configured version or can be set explicitly.

What you’ll achieve

You ask your assistant to query an InfluxDB-backed metric; the assistant uses the server’s InfluxDB query tool to post the query through Grafana’s datasource proxy and return the points. The server is a thin shim over Grafana’s /api/ds/query endpoint, so Grafana handles all protocol details for InfluxDB v1 and v2.

Before you begin

The server set up and configured with access to Grafana.
The InfluxDB tool category must be enabled (it’s disabled by default, like the other optional datasource tools). Add influxdb to Enable and disable tools.
An InfluxDB datasource configured in Grafana. The service account must have datasources:query and scope for that datasource (for example, datasources:uid:<uid>).

Run a query

In your MCP client, ask the assistant to query InfluxDB. For example, “What was the mean CPU usage on the host server1 in the last hour?” or “Run this Flux: from(bucket: \"metrics\") |> range(start: -1h) |> filter(fn: (r) => r._measurement == \"cpu\").” The assistant uses the server’s query_influxdb tool with the datasource UID, query string, and time range.

If the datasource is configured for InfluxDB v2 (Flux), pass a Flux query. If it’s configured for v1 (InfluxQL), pass an InfluxQL query. You can override the dialect explicitly by setting dialect to "flux" or "influxql".

Run a panel’s query from a dashboard

If a dashboard you care about already contains the InfluxDB panel you want, use run_panel_query instead of writing the query yourself. The MCP server fetches the dashboard, extracts the panel’s query and queryType, substitutes any template variables, and executes the query against the configured datasource. This is the fastest path from “what does this panel show?” to actual data.

Discover what’s in a bucket or database

The server does not expose dedicated measurement- or tag-listing tools. Instead, run discovery queries via query_influxdb:

Flux (v2): from(bucket: "my-bucket") |> range(start: -1h) |> limit(n: 5) to see available fields and tags on recent points.
InfluxQL (v1): SHOW MEASUREMENTS, SHOW TAG KEYS FROM "cpu", SHOW FIELD KEYS FROM "cpu".

Use get_query_examples with datasourceType: "influxdb" to see more starter queries for both dialects.

Next steps

Query metrics with Prometheus for PromQL use cases.
Run a dashboard panel query to execute a panel’s query from the MCP server.