Grafana MCP for Claude Code: Direct Access to Dashboards, Metrics, and Alerts

When production breaks, the traditional troubleshooting flow often looks like this: open Grafana, find the right dashboard, stare at a spiking curve for a while, copy a PromQL query or Loki log, paste it into the terminal, and repeat the whole thing when Claude asks for a wider time range. You become a slow, lossy copy-paste channel between your metrics system and your AI agent.

Grafana MCP is built to solve exactly this problem. It's the official MCP server from Grafana Labs, letting Claude Code search dashboards on its own, run PromQL against Prometheus, run LogQL against Loki, read alert rules and their firing states, and even find incident records. It supports self-hosted Grafana 9.0+ as well as Grafana Cloud, and is open source under Apache 2.0.

It pairs especially well with Sentry MCP: Sentry tells Claude which error is occurring, while Grafana shows when it started and what the metrics looked like at that moment.

What Grafana MCP Can Do

Grafana MCP splits Grafana's core capabilities into several tool groups exposed to Claude Code, each corresponding to a class of executable query actions.

Tool group	What Claude can do
Dashboards	Search dashboards, get concise summaries, extract single properties with JSONPath, read the query behind each panel
Prometheus	Run instant and range PromQL queries, list metrics and label names, compute p50/p90/p95/p99 from histograms
Loki	Run LogQL log and metric queries, list labels, extract detected log patterns
Alerting	List alert rules and their states (firing, normal, error), read notification policies and contact points
Incidents & Sift	Search incidents, and run Sift on Grafana Cloud to check log error patterns and slow requests
--disable-write	Removes all create, update, and delete tools, so the agent can only look, not touch

The key to this tool design is restraint. The --disable-write flag strips out every write operation entirely, and combined with a Viewer-role token, Claude can only read data — it can't touch your dashboards or alert configurations. When it comes to connecting AI agents to production monitoring systems, permission boundaries matter far more than feature count.

MCP (Model Context Protocol) is an open protocol introduced by Anthropic in 2024 to let large language model applications connect to external tools and data sources in a standardized way. Think of MCP as the "USB-C port" of the AI world: the model side only needs to implement a client once, and any server that follows the protocol can be discovered and invoked. An MCP server exposes a number of "tools", "resources", and "prompt templates" over transports like stdio, SSE, or HTTP; Claude initiates calls on demand, reads the results into context, and then decides what to do next. It's this protocol that lets Claude Code query systems like Grafana and Sentry directly, without needing a custom plugin for every monitoring backend.

Five-Minute Setup

Prerequisites

Requirement	Why you need it	Time
Grafana 9.0 or later (self-hosted or Cloud)	Datasource tools depend on API endpoints added in 9.0	0 min
Service account token	How the server authenticates to Grafana; the Viewer role is enough for read-only use	~2 min
uv installed	uvx mcp-grafana runs the server for quick startup, no global install needed	~1 min
Claude Code installed	The client that calls the Grafana tools	0 min

Create a Token and Connect

In Grafana, go to Administration → Users and access → Service accounts, create a new service account, assign it the Viewer role, then generate a token and copy it — it's only shown once.

Then run:

claude mcp add --scope user --transport stdio grafana \
  --env GRAFANA_URL=http://localhost:3000 \
  --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token> \
  -- uvx mcp-grafana --disable-write

Replace <your-token> with your actual token, and if you're on Grafana Cloud, swap the URL for something like https://myinstance.grafana.net. Restart Claude Code, then run claude mcp list to confirm the connection status.

--scope user makes this server available across all projects. Arguments after -- are passed to the server itself, and --disable-write falls into that category.

uv and uvx are Python package management and execution tools built in Rust by the Astral team. uvx (equivalent to uv tool run) can pull and run a command-line tool from PyPI without a prior global install, resolving dependencies in an isolated temporary environment. For "use-it-and-forget-it" utilities like MCP servers, uvx mcp-grafana means no pip install, no worrying about virtual environments or version conflicts, and upgrades happen automatically the next time you run it. This is why the official recommendation is to launch mcp-grafana with uvx rather than pip — the install step goes from "install a Python package" to "make sure uv is on the machine."

Let Claude Do the Install Itself

If you'd rather not do it by hand, you can hand the install task straight to the agent. The prompt below has Claude perform the install and verification itself; step 5 requires it to actually call the Grafana search tool and list the top 5 dashboard titles before it can claim success:

You have shell access and the `claude mcp` CLI on this machine. Connect the Grafana MCP server (grafana/mcp-grafana) to Claude Code in read-only mode, then report the result. Do not tell me you're done unless step 5 actually confirms success:

1. Run `uvx --version`. If uv is missing, install it with the official install script for the appropriate system and re-check.
2. Run `claude mcp list`. If a grafana entry already exists, stop and show its configuration rather than adding it again.
3. Ask me for two values: the Grafana URL and a service account token. Tell me to create the token in Grafana under Administration > Users and access > Service accounts, with the Viewer role. Never echo the token in the conversation, and never write it to any file other than the Claude Code config.
4. Add the server for all projects, in read-only mode:
   `claude mcp add --scope user --transport stdio grafana --env GRAFANA_URL=<url> --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<token> -- uvx mcp-grafana --disable-write`
5. Run `claude mcp list` to confirm grafana shows Connected. Then call the Grafana search tool and list the top 5 dashboard titles.

If any step fails, tell me the exact error and the command that produced it. A 400 "id is invalid" from the datasource tools means Grafana is older than 9.0 — say so directly instead of retrying. Don't skip any step.

The agent can't create the service account token for you, so the prompt stops at that step to ask you for it. This is intentional: the role permissions are yours to decide.

Extending Datasources and Verifying the Setup

Enable Extra Datasources On Demand

Prometheus, Loki, dashboards, alerting, and incidents are enabled by default. Other datasources need to be explicitly enabled, such as sql, cloudwatch, elasticsearch, influxdb, and others, by specifying them with the --enabled-tools flag. Conversely, you can also disable categories you never use with --disable-oncall, keeping Claude's tool list lean — the more tools there are, the higher the chance the model picks the wrong one.

PromQL and LogQL are the query languages for Prometheus and Loki, respectively. PromQL is oriented toward time series and supports functions like rate() and histogram_quantile() for computing error rates, percentiles, and similar metrics; the p50/p90/p95/p99 mentioned in the article are derived from histogram metrics aggregated via histogram_quantile(). LogQL targets log streams, and can filter logs using label selectors (e.g., {app="api"} |= "error"), or aggregate logs into metrics using a pipeline syntax similar to PromQL. Grafana MCP wraps both query languages into tools so Claude can construct queries directly without understanding the underlying HTTP API.

Confirm the Server Is Actually Working

After running claude mcp list, you might see three states:

• ✔ grafana — Connected, meaning the server started. Note that it only contacts Grafana when a tool is actually invoked.
• ! grafana — 401 Unauthorized, meaning the token is wrong or has been deleted and needs to be recreated.
• ✘ grafana — Failed to connect; run uvx mcp-grafana --help to see the real error.

Then give Claude a real question to verify the pipeline is working:

Search my Grafana dashboards, pick the one for the API service, and tell me whether the error rate has changed over the past 6 hours

If Claude first calls the dashboard search tool, then a Prometheus or Loki query tool, and finally answers with real numbers from your data, that means the token, URL, and datasource access are all working correctly.

Five Common Setup Pitfalls

Giving the token admin permissions to save effort. An AI agent holding an Admin token can delete dashboards and alert rules. Start with Viewer and --disable-write, and only escalate when you genuinely need write tools.

Putting server arguments before --. --disable-write belongs to mcp-grafana, not to claude mcp add. If you put it before the double dash, Claude Code will reject or ignore it.

Continuing to use the old GRAFANA_API_KEY variable. It still works but is deprecated; new configurations should use GRAFANA_SERVICE_ACCOUNT_TOKEN.

Asking for the entire dashboard back. A full dashboard JSON eats up a huge amount of context window. Request a summary or specific panels instead — the server provides dedicated tools for this.

Grafana version older than 9.0. Datasource tools will report 400 … "id is invalid". The fix is upgrading Grafana, not reconfiguring the server.

Official Resources

• grafana/mcp-grafana on GitHub — README, full tool list, and all CLI flags
• Grafana service accounts — how to create tokens and choose roles
• Claude Code MCP docs — options and scopes for claude mcp add

The server itself is Apache 2.0 open source and free to use; all you need is a Grafana instance, whether that's the free Grafana Cloud tier or self-hosted OSS. Grafana Cloud users just set GRAFANA_URL to their stack address, and some tools (like Sift investigations) are only available on Cloud. To remove it, run claude mcp remove grafana --scope user, and remember to delete the corresponding service account token in Grafana to prevent it from being reused.

The value of connecting monitoring data to an AI agent isn't saving a few mouse clicks — it's that when Claude can pull metrics, logs, and alert states on its own, its judgments are backed by data instead of guesses.