Working with Grafana MCP

Overview

Grafana MCP provides tools for observability: dashboards, metrics (Prometheus), logs (Loki), alerting, and incident management. Always start with datasource discovery - most queries require a datasource UID.

Core Workflow

1. list_datasources → Find datasource UID
2. Use datasource-specific tools with that UID

Quick Reference

Task	Tool(s)	Notes
Find datasources	list_datasources	Filter by type: 'prometheus', 'loki'
Search dashboards	search_dashboards	Returns UID, title, folder
Dashboard overview	get_dashboard_summary	Lightweight - use first
Specific dashboard data	get_dashboard_property	JSONPath: $.panels[*].title
Full dashboard JSON	get_dashboard_by_uid	Heavy - use sparingly
Query metrics	query_prometheus	Needs datasource UID
Query logs	query_loki_logs	LogQL syntax
List alerts	list_alert_rules	Grafana-managed by default
Current incidents	list_incidents	Filter by status

Datasource Discovery

Always first step - most operations need a datasource UID:

# Find all Prometheus datasources
grafana_list_datasources(type="prometheus")

# Find Loki datasources
grafana_list_datasources(type="loki")

Returns: id, uid, name, type, isDefault

Dashboard Access (Context-Efficient)

Prefer lightweight tools:

Need	Use	Avoid
Dashboard exists?	search_dashboards	-
Panel count, types	get_dashboard_summary	get_dashboard_by_uid
Panel titles	get_dashboard_property with $.panels[*].title	get_dashboard_by_uid
Single panel	get_dashboard_property with $.panels[0]	get_dashboard_by_uid
Panel queries	get_dashboard_panel_queries	get_dashboard_by_uid
Full JSON	get_dashboard_by_uid	-

JSONPath examples:

• $.title - Dashboard title
• $.panels[*].title - All panel titles
• $.panels[0].targets[0].expr - First panel's query
• $.templating.list - Template variables

Prometheus Queries

# Instant query (single point)
grafana_query_prometheus(
    datasourceUid="PROM_UID",
    expr="up{job='myapp'}",
    startTime="now",
    queryType="instant"
)

# Range query (time series)
grafana_query_prometheus(
    datasourceUid="PROM_UID",
    expr="rate(http_requests_total[5m])",
    startTime="now-1h",
    endTime="now",
    stepSeconds=60,
    queryType="range"
)

Time formats: RFC3339 or relative (now, now-1h, now-30m)

Discover metrics:

# List metric names
grafana_list_prometheus_metric_names(datasourceUid="UID", regex="http.*")

# List label names
grafana_list_prometheus_label_names(datasourceUid="UID")

# List label values
grafana_list_prometheus_label_values(datasourceUid="UID", labelName="job")

Loki Log Queries

# Simple label query
grafana_query_loki_logs(
    datasourceUid="LOKI_UID",
    logql='{app="myapp"}',
    limit=50
)

# With filter
grafana_query_loki_logs(
    datasourceUid="LOKI_UID",
    logql='{app="myapp"} |= "error"',
    startRfc3339="2025-01-01T00:00:00Z",
    endRfc3339="2025-01-01T01:00:00Z"
)

LogQL patterns:

• {label="value"} - Label selector
• |= "text" - Line contains
• != "text" - Line does not contain
• |~ "regex" - Regex match
• | json - Parse JSON
• | logfmt - Parse logfmt

Check stream size first:

grafana_query_loki_stats(datasourceUid="UID", logql='{app="myapp"}')
# Returns: streams, chunks, entries, bytes

Alerting

List alerts:

grafana_list_alert_rules()  # Grafana-managed

# With label filter
grafana_list_alert_rules(
    label_selectors=[{"filters": [
        {"name": "severity", "type": "=", "value": "critical"}
    ]}]
)

Create alert rule:

grafana_create_alert_rule(
    title="High CPU Usage",
    ruleGroup="cpu-alerts",
    folderUID="alert-folder",
    condition="B",  # Reference to reducer
    data=[
        {
            "refId": "A",
            "datasourceUid": "PROM_UID",
            "model": {
                "expr": "avg(cpu_usage) > 80",
                "intervalMs": 1000,
                "maxDataPoints": 43200
            }
        },
        {
            "refId": "B",
            "datasourceUid": "__expr__",
            "model": {
                "type": "reduce",
                "expression": "A",
                "reducer": "last"
            }
        }
    ],
    noDataState="NoData",
    execErrState="Alerting",
    for_="5m",
    orgID=1
)

Incidents & OnCall

# List active incidents
grafana_list_incidents(status="active")

# Get incident details
grafana_get_incident(id="incident-id")

# Who's on call?
grafana_list_oncall_schedules()
grafana_get_current_oncall_users(scheduleId="schedule-id")

Dashboard Updates

Prefer patch operations for small changes:

grafana_update_dashboard(
    uid="dashboard-uid",
    operations=[
        {"op": "replace", "path": "$.title", "value": "New Title"},
        {"op": "replace", "path": "$.panels[0].title", "value": "Panel 1"}
    ],
    message="Updated titles"
)

Append to arrays:

• $.panels/- - Append to panels array
• $.panels[2]/- - Append to nested array

Common Mistakes

Mistake	Fix
Query without datasource UID	Always list_datasources first
get_dashboard_by_uid for simple info	Use get_dashboard_summary or get_dashboard_property
Loki query without checking size	Use query_loki_stats first for large ranges
Missing queryType in Prometheus	Specify instant or range
Alert without proper condition chain	Need query (A) → reducer (B) → condition references B

Investigation Tools

For troubleshooting, Grafana provides analysis tools:

# Find error patterns in logs
grafana_find_error_pattern_logs(
    name="App Errors Investigation",
    labels={"app": "myapp"}
)

# Find slow requests
grafana_find_slow_requests(
    name="Slow API Investigation",
    labels={"service": "api"}
)