Grafana MCP for AI Agents

What Is Grafana MCP

Grafana ships an official MCP (Model Context Protocol) server that exposes Grafana capabilities as tools any MCP-compatible AI agent can call. Instead of copy-pasting PromQL results or dashboard URLs into chat, the agent queries Prometheus, Loki, and dashboards autonomously during a conversation.

MCP is an open protocol. The same Grafana MCP server works with any client that supports it:

What the Agent Can Do

Setup

Prerequisites

• Grafana instance with API access (self-hosted or Grafana Cloud)
• Grafana service account token — minimum Viewer role for read operations; Editor needed for creating incidents, annotations, or editing dashboards

Install the MCP server

# Option A — Node.js (npx, no install needed)
npx -y @grafana/mcp-grafana

# Option B — Python (uvx, no install needed)
uvx mcp-grafana

# Option C — install globally
npm install -g @grafana/mcp-grafana

Configure per AI client

All clients need two env vars:

• GRAFANA_URL — your Grafana base URL
• GRAFANA_SERVICE_ACCOUNT_TOKEN — service account token (canonical var name; GRAFANA_API_KEY is accepted for legacy back-compat)

Claude Code — .mcp.json in project root or ~/.claude/mcp.json globally:

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@grafana/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "${GRAFANA_SERVICE_ACCOUNT_TOKEN}"
      }
    }
  }
}

GitHub Copilot (VS Code) — .vscode/mcp.json in workspace:

{
  "servers": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@grafana/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "${GRAFANA_SERVICE_ACCOUNT_TOKEN}"
      }
    }
  }
}

OpenCode — opencode.json in project root:

{
  "mcp": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@grafana/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "${GRAFANA_SERVICE_ACCOUNT_TOKEN}"
      }
    }
  }
}

After saving, restart the AI client. The Grafana tools will appear in the tool list.

Keep the token out of git

All config snippets above use ${GRAFANA_SERVICE_ACCOUNT_TOKEN} — an env var reference, not the raw token. Set the actual token value in your shell profile (e.g. ~/.zshrc) or a secrets manager. Never commit the raw token value.

# In ~/.zshrc or ~/.bashrc
export GRAFANA_SERVICE_ACCOUNT_TOKEN="glsa_..."  # generated in Grafana → Service Accounts

Practical Examples

These prompts work in any MCP-compatible client.

Investigate a CPU spike

Check why hungryhub-server CPU is high in hh-end-user-public right now.
Show actual usage vs the configured request and limit.

Agent runs rate(container_cpu_usage_seconds_total{...}[5m]) via query_prometheus, then pulls error logs from Loki for the same window.

Find recent errors in a namespace

Show error logs from hh-end-user-public in the last 30 minutes.
Group by error message and show count per pattern.

Agent calls find_error_pattern_logs or query_loki_logs with {namespace="hh-end-user-public"} |= "error".

Verify KEDA autoscaling fired

Did KEDA scale hungryhub-server up during 06:00–09:00 Jakarta time today?
Show replica count over that window.

Agent queries keda_scaledobject_replicas_count or kube_deployment_spec_replicas over the time range.

Check Cluster Autoscaler activity

Did Cluster Autoscaler remove any nodes in the last 2 hours?
Show which nodes were drained and when.

Agent calls query_loki_logs targeting cluster-autoscaler pod in kube-system, filtering for “Removing node”.

Get a dashboard panel as image

Show me the Node CPU utilization panel from the EKS overview dashboard.

Agent calls get_panel_image and returns the PNG inline (requires Grafana Image Renderer plugin).

Create an incident

Create a Grafana incident: "hungryhub-server OOM in hh-end-user-public",
severity=critical, assign to the on-call engineer.

Agent calls get_current_oncall_users then create_incident. Requires Editor role.

Prompting Tips

Specify time ranges explicitly. Grafana MCP accepts:

• Relative: now-1h, now-30m, now-6h
• Absolute with timezone offset: 2026-06-07T06:00:00+07:00

Name namespace and workload exactly. Label selectors are exact-match. “hungryhub-server” is ambiguous across 4 namespaces — always include namespace=.

Ask for the raw query. The agent can output the PromQL or LogQL it used, so you can paste it into a dashboard panel.

Chain metrics + logs in one prompt. The agent can fan out to both Prometheus and Loki in the same turn.

Limitations

• Read-only for metrics/logs — no write path to Prometheus or Loki.
• Dashboard edits are live — update_dashboard modifies the real dashboard immediately. Use with caution or restrict to Editor-capable tokens only where intended.
• Image rendering requires the Grafana Image Renderer plugin installed on your Grafana instance.
• Sift investigations are Grafana Cloud-only; not available on self-hosted.
• Rate limits — heavily parallel agent tool calls against a single Grafana instance can hit API rate limits; add step intervals to PromQL range queries to reduce data volume.

Related

• EKS Cost Optimization 2026 — real example of using Grafana metrics to verify CA and KEDA behavior
• Kubernetes CPU Request Rightsizing — PromQL patterns for CPU usage analysis