When something breaks in production, the usual Claude Code loop is: open Grafana, find the right dashboard, squint at a spike, copy a PromQL query or a chunk of Loki logs, paste it into the terminal, and repeat when Claude asks for a wider time range. You end up as a slow, lossy copy-paste bridge between your metrics and your agent.
Grafana MCP is Grafana Labs’ official MCP server. It lets Claude Code search your dashboards, run PromQL against Prometheus and LogQL against Loki, read alert rules and their firing state, and look up incidents on its own. It works with self-hosted Grafana 9.0+ and Grafana Cloud, and it’s open source (Apache 2.0).
Pair it with our Sentry MCP guide: Sentry tells Claude which error is happening, Grafana shows when it started and what the metrics were doing around it.
Quick Start
Create a Grafana service account token with the Viewer role (Administration → Users and access → Service accounts), 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 token, and swap the URL for your Grafana Cloud address (https://myinstance.grafana.net) if you use Cloud. Restart Claude Code and run claude mcp list. Total time: about 5 minutes.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
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 and report back. Do not tell me it's done unless step 5 actually confirms it:
1. Run `uvx --version`. If uv is missing, install it with the official installer for this OS (macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`, Windows PowerShell: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`), then re-check.
2. Run `claude mcp list`. If a grafana entry already exists, stop and show me its config instead of adding a second one.
3. Ask me for two values: my Grafana URL (e.g. http://localhost:3000 or https://myinstance.grafana.net) 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 back in chat or write it to any file other than the Claude Code config.
4. Add the server for all projects, read-only:
`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` and confirm grafana shows Connected. Then call the Grafana search tool and list the first 5 dashboard titles.
If any step fails, give me the exact error and the command that produced it. A 400 "id is invalid" error on datasource tools means Grafana is older than 9.0, so say that instead of retrying. Do not skip ahead.
The agent can’t create the service account token for you, so the prompt stops and asks for it. That’s intentional: you decide what role the token gets.
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Grafana 9.0 or later (self-hosted or Cloud) | Datasource tools use API endpoints that were added in 9.0 | 0 min |
| A service account token | How the server authenticates to Grafana. Viewer is enough for read-only use | ~2 min |
| uv installed | The Quick Start runs the server with uvx mcp-grafana, no global install needed |
~1 min |
| Claude Code installed | The client that calls the Grafana tools | 0 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Check uv (and optionally start a test Grafana)
~1 min
Confirm uv is available:
uvx --version
No Grafana to test against? Start a throwaway local one with Docker, then sign in at http://localhost:3000 (admin / admin):
docker run -d --name grafana -p 3000:3000 grafana/grafana
Step 2 — Create a service account token
~2 min
In Grafana, go to Administration → Users and access → Service accounts, select Add service account, give it the Viewer role, then Add service account token and copy it. You won’t see it again.
Want Claude to create dashboards or silence alerts later? Give the account the Editor role instead and drop --disable-write in Step 3.
Step 3 — Add the server to Claude Code
~1 min
--scope user makes it available in every project. Everything after -- is passed to the server, which is where --disable-write goes:
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
Real run, October 2026, Claude Code 2.1.291. Keep the server name before the --env flags: placed after them, Claude Code reads it as one more variable and stops with Invalid environment variable format. Connected means the server started; it only calls Grafana when a tool runs.
Step 4 — Turn on extra datasources (optional)
~1 min
Prometheus, Loki, dashboards, alerting, and incidents are on by default. Other datasources are off until you enable them with --enabled-tools, for example sql, cloudwatch, elasticsearch, or influxdb. You can also switch off categories you never use, such as --disable-oncall, to keep Claude’s tool list short.
Claude Code queries the same dashboards, metrics, and alerts you check during an incident.
What Each Piece Does
| Tool Group | What Claude Can Do With It |
|---|---|
| Dashboards | Search dashboards, get a compact summary, pull a single property with JSONPath, and read each panel’s queries |
| Prometheus | Run instant and range PromQL queries, list metric and label names, and compute p50/p90/p95/p99 from histograms |
| Loki | Run LogQL log and metric queries, list labels, and pull detected log patterns |
| Alerting | List alert rules with their state (firing, normal, error) and read notification policies and contact points |
| Incidents & Sift | Search incidents and, on Grafana Cloud, run Sift checks for error patterns in logs and slow requests |
--disable-write |
Removes every create, update, and delete tool, so the agent can look but not touch |
Verify It’s Actually Working
claude mcp list
✔ grafana uvx mcp-grafana –disable-write – Connected
! grafana 401 Unauthorized → token is wrong or was deleted; create a new one
✘ grafana Failed to connect → run uvx mcp-grafana --help to see the real error
Then give Claude a real question:
Search my Grafana dashboards, pick the one for the API service, and tell me if the error rate changed in the last 6 hours
If Claude calls a dashboard search tool, then a Prometheus or Loki query tool, and answers with actual numbers from your data, the token, the URL, and the datasource access are all working.
Common Mistakes to Avoid
-
Giving the token Admin because it’s easier. An AI agent with an Admin token can delete dashboards and alert rules. Start with Viewer and
--disable-write, and move up only when you need a write tool. -
Putting server flags before the
--.--disable-writebelongs tomcp-grafana, not toclaude mcp add. Placed before the double dash, Claude Code rejects it or ignores it. -
Using the old
GRAFANA_API_KEYvariable. It still works but is deprecated. UseGRAFANA_SERVICE_ACCOUNT_TOKENfor new setups. - Asking for a whole dashboard. Full dashboard JSON can eat a large chunk of the context window. Ask for the summary or specific panels instead; the server has dedicated tools for exactly that.
-
Running Grafana older than 9.0. Datasource tools fail with
400 … “id is invalid”. The fix is upgrading Grafana, not reconfiguring the server.
Q&A
Is it free?
Yes. The server is open source under Apache 2.0. You need a Grafana instance, and the free Grafana Cloud tier or a self-hosted OSS install both work.
Does it work with Grafana Cloud?
Yes. Set GRAFANA_URL to your stack address, such as https://myinstance.grafana.net, and use a service account token from that stack. Some tools, like Sift investigations, only exist on Cloud.
Can Claude change my dashboards or alerts?
Not with the setup in this guide. --disable-write removes the write tools, and a Viewer token can’t write anyway. Remove both only if you want Claude to edit things.
I don’t use uv. Are there other ways to run it?
Yes. The project also ships a Docker image, prebuilt binaries, and a Helm chart. The README’s Usage section covers each one.
How do I remove it?
claude mcp remove grafana --scope user, then delete the service account token in Grafana so it can’t be reused.
Official Resources
- grafana/mcp-grafana on GitHub — README, full tool list, and every CLI flag
- Grafana service accounts — how to create the token and pick a role
-
Claude Code MCP docs —
claude mcp addoptions and scopes
Originally published at quickpromptco.com, where the guide is kept up to date.
Top comments (0)