grafana MCP

The Grafana MCP server connects an agent to your Grafana instance, local or Grafana Cloud. The agent can find dashboards, read their queries, run Prometheus and Loki queries, look at alerts, open incidents and see who is on call. It is Apache-2.0 licensed and made by Grafana Labs. We checked it on 31 October 2026. The latest release was v2.1.1.

Quick facts

What it does

Most outages are solved by reading three things: a dashboard, a log line and an alert. The server lets an agent do all three without you copying screenshots into a chat. You can ask "which panels on the checkout dashboard use the orders datasource" or "show error logs for the payments service in the last hour", and the agent calls tools that talk to Grafana's API.

The README groups the features like this:

• Dashboards. Search, fetch by UID, list versions, get a compact summary, extract parts with JSONPath, patch or update a dashboard, and pull panel queries with their datasource.
• Datasources and queries. List datasources and query Prometheus, Loki, and, when enabled, InfluxDB, SQL sources, CloudWatch, Google Cloud Logging, Graphite, Elasticsearch or OpenSearch and Quickwit.
• Tracing and profiles. Tempo and Pyroscope tools.
• Alerting. List and fetch rules, create, update and delete them, and manage routing such as notification policies and contact points.
• Incidents and OnCall. Search, create and update incidents. Read schedules, shifts, the current on-call user and alert groups.
• Annotations, snapshots, rendering and deeplinks. Create annotations, take snapshots, render panels and generate links.
• Admin. Teams, users, roles and permissions. Off by default.
• Grafana Assistant. Send a prompt to the Grafana Assistant plugin and wait for its reply. Off by default and needs the plugin.
• Agent observability. Grafana Cloud only, off by default.

Our view: this is closer to a full Grafana client than a dashboard reader. That is its strength and its risk.

Context window warnings

The README is open about token cost. Fetching a large dashboard by UID "can consume significant context window space", and so can updating one, since update needs the full JSON. It offers cheaper tools for the same job:

Tell your agent to prefer the summary and property tools. If you write the instructions file for your agents, put that line in it.

Tool groups and defaults

The tool table in the README lists the tool, its category, the RBAC permissions it needs and the scopes. Categories include Admin, Alerting, Annotations, CloudWatch, Dashboard, Datasources, Incident, Loki, OnCall, Prometheus, Provisioning, Pyroscope, Rendering, Search, Snapshot, SQL, Tempo and more. The table grows with releases, so we give no count.

Several categories are off by default. You add them with --enabled-tools:

A category you do not need can also be switched off with --disable-<category>, for example --disable-oncall or --disable-navigation.

What it costs

The server is free and open source. Grafana itself may or may not cost you anything: self-hosted Grafana OSS is free to run, and Grafana Cloud has its own plans. Some tools need parts of the wider stack, for example Grafana Incident, OnCall, the Grafana Assistant plugin or the Google Cloud Logging datasource plugin version 1.8.0 or later. The README notes that plugin needs Grafana 11.2 or newer. Check Grafana's pricing page for which Cloud plans include them.

Install it

You need a Grafana URL and a service account token. The README's steps:

1. Create a service account in Grafana with permissions for the tools you want.
2. Generate a token for it.
3. Pass both to the server as environment variables.

The simplest permission shortcut, per the README, is the built-in Editor role, "a simpler (but less restrictive) option". We would only use that on a test instance. For production, give a role with read permissions only and add scopes as you need them.

With uvx

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

This needs uv installed. For Grafana Cloud, change GRAFANA_URL to your instance address.

With Docker

docker run --rm -i \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana -t stdio

With Go

GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest

As a shared HTTP server

Run with -t streamable-http and --address, which defaults to localhost:8000. The README documents a MCP_GRAFANA_SERVER_TOKEN variable for caller authentication, TLS options and a health check endpoint. It also validates Host and Origin headers on every route of the MCP listener, which blocks DNS-rebinding attacks from a browser.

The old GRAFANA_API_KEY variable still works but is deprecated. Use GRAFANA_SERVICE_ACCOUNT_TOKEN. You can also point GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE at a file, and the server rereads it on every request, so a rotated token is picked up without a restart.

Install it in each agent

The README shows the JSON entry for clients such as Claude Desktop and Cursor. Lines for the other agents are our adaptation from each agent's own MCP docs. For how agents name fields, see MCP clients.

Claude Code

Our adaptation:

claude mcp add grafana \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -- uvx mcp-grafana

Codex

Our adaptation, in ~/.codex/config.toml:

[mcp_servers.grafana]
command = "uvx"
args = ["mcp-grafana"]

[mcp_servers.grafana.env]
GRAFANA_URL = "http://localhost:3000"
GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your service account token>"

Cursor

The README's JSON entry, shown above, goes in ~/.cursor/mcp.json or .cursor/mcp.json.

Antigravity

Our adaptation. Add the same stdio entry to ~/.gemini/config/mcp_config.json under mcpServers. For a shared Streamable HTTP deployment, Antigravity uses serverUrl. Antigravity's MCP docs say a headers object sends custom HTTP headers with serverUrl connections, so a bearer header is possible. Gemini CLI is now Code Assist enterprise only, so we do not give a line for it.

OpenCode

Our adaptation, in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "grafana": {
      "type": "local",
      "command": ["uvx", "mcp-grafana"],
      "environment": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "{env:GRAFANA_SERVICE_ACCOUNT_TOKEN}"
      }
    }
  }
}

Configuration worth knowing

A service account token is tied to one organization. If you need several, the README describes per-call organization selection for credentials that span more than one.

Security notes

Grafana can hold a lot of sensitive material: logs with customer data, SQL datasources pointing at production databases, alert contact details. The server hands whatever the token can reach to the model provider.

• Read-only mode. --disable-write removes dashboard update, folder creation, incident changes, alerting write tools, annotation and snapshot writes, OnCall alert group updates and the Assistant. It also removes the raw-SQL query tools (query_sql, query_influxdb) unless you add --enable-query, a detail worth knowing.
• Query-free mode. --disable-query removes every tool that runs a datasource query, such as query_prometheus, query_loki_logs and run_panel_query, and it wins over --enable-query. You keep discovery tools. This suits an agent that should know what exists but never read log content.
• Loki cost. A broad Loki selector over a wide range can scan a huge amount of data. The README says Loki does not enforce its byte limit on log queries without a line filter, and offers the guardrail mode for that.
• Least privilege. The README lists RBAC permissions and scopes for each tool, so you can build a role that matches exactly what you enable.
• Admin tools are off by default for a reason. Leave them off.
• Usage statistics. Reporting is on by default and sent every 4 hours and on shutdown. The README says tool arguments, resource names, queries, log lines, error messages and credentials are never sent, and there is no session identifier. If your policy says no telemetry, set --usage-stats=disabled or DO_NOT_TRACK=1.
• Shared deployments. Use TLS, set MCP_GRAFANA_SERVER_TOKEN, and review --allowed-hosts.

Example work, and what to check

After any dashboard write, list_dashboard_versions shows saved versions with author and time, so you can roll back by hand.

Limits and known issues

• Version support: Grafana 9.0 or later. Older versions may lack API endpoints for datasource operations.
• Large dashboards cost many tokens. Use the summary and property tools.
• Some categories need plugins or Grafana Cloud. Agent observability works only in Grafana Cloud.
• Tool names and groups change across major versions. The Go import path includes /v2/. The 2.0 release notes say the major bump is for the Go library: the server moved from mark3labs/mcp-go to the official MCP Go SDK, whose types are part of the module's exported API.

Alternatives

Which agents it suits

Any agent that supports MCP stdio can run it. It is a good fit for coding agents used by on-call engineers, because incident work needs data from several places in one session. Because of the number of tools, an agent with a small tool budget benefits from --enabled-tools to keep the list short. Fewer tool descriptions also means fewer tokens spent on setup.

Our take

For a team already on Grafana, this is one of the more complete servers we have read about. It has read-only and query-free modes, per-tool permission tables, Loki guardrails and a clear note on context cost. Those are the details that show someone has thought about an agent pointed at production telemetry.

We would start with --disable-write and a service account that has read rights on a few dashboards. Add Prometheus and Loki queries once you trust the model's PromQL. Leave admin and Assistant off. If you run Loki, turn on the guardrail in shadow mode first and see what it would block.

This is our reading of the documentation, not a hands-on test.

A short setup checklist

1. Confirm Grafana is 9.0 or later.
2. Create a service account with read-only permissions.
3. Install uv and add the server with GRAFANA_URL and the token.
4. Start with --disable-write.
5. Decide whether to disable usage statistics.
6. Enable extra categories one at a time with --enabled-tools.
7. Set the Loki guardrail to shadow, then enforce.
8. Add a line to your agent instructions to use dashboard summaries first.

See also the MCP server list and best MCP servers.

Frequently asked questions

What does the Grafana MCP server do?

It gives an agent access to a Grafana instance for dashboards, datasource queries, alerting, incidents and on-call data.

Does it work with Grafana Cloud?

Yes. Use your instance URL and a service account token.

Can I stop it from changing anything?

Yes. Use --disable-write, and add --disable-query to remove query tools as well.

Which Grafana version do I need?

Grafana 9.0 or later, per the README.

Does the server send usage data to Grafana Labs?

Anonymous statistics are on by default. Disable them with --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled or DO_NOT_TRACK=1.