How to add Grafana MCP to Claude Code

5 min read.
Tags: AIClaude Code

The Grafana MCP server lets Claude Code search your dashboards, run PromQL and LogQL queries, and read alert rules and incidents from a Grafana instance. Adding Grafana MCP to Claude Code takes a service account token and one claude mcp add command, with no browser login.

Quick command

claude mcp add grafana \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token \
  -- uvx mcp-grafana

The Datadog, PagerDuty and Sentry servers are hosted endpoints you log in to through /mcp. The Grafana MCP server (mcp-grafana) runs on your machine over stdio and talks to the Grafana API with the token you give it. That's why there's no --transport http here and no OAuth step.

For self-hosted Grafana, swap the URL for your own, like http://localhost:3000. The server needs Grafana 9.0 or later. On older versions the datasource tools fail because the /datasources/uid/{uid} API doesn't exist yet.

Put the server name before -e

Get the order wrong and the command fails:

# fails
claude mcp add -e GRAFANA_URL=https://myinstance.grafana.net grafana -- uvx mcp-grafana
Invalid environment variable format: grafana, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

-e takes more than one value, so it swallows grafana as another environment variable. Put the name right after add, then the -e flags, then -- and the command. Everything after -- goes to mcp-grafana, not to Claude Code.

Create the service account token

In Grafana, go to Administration → Users and access → Service accounts, create a service account, and add a token to it. Grafana tokens start with glsa_.

The role decides what Claude can do. Viewer covers most of the read tools: searching dashboards, querying datasources, reading alert rules. The mcp-grafana README suggests Editor if you don't want to set up fine-grained RBAC, and also says it's less restrictive than scoped permissions. If you only want Claude to look, give it Viewer and run the server read-only (below).

Install mcp-grafana

The quick command uses uvx, which fetches mcp-grafana from PyPI and runs it whenever Claude Code starts the server. You need uv installed. If you'd rather not use uv, there are two other options.

A binary from the releases page, or built with Go:

go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest

Note the /v2 in the module path. Then point Claude Code at the binary:

claude mcp add grafana \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token \
  -- mcp-grafana

Or Docker:

claude mcp add grafana -- docker run --rm -i \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token \
  grafana/mcp-grafana -t stdio

The Docker image starts in SSE mode by default, so -t stdio is required, and -i keeps stdin open for Claude Code to talk to it. Here the -e flags sit after --, so they belong to docker run, not to Claude Code.

Verify it works

claude mcp get grafana

Then ask about something you know exists:

List my Grafana dashboards in the Production folder.

Real dashboard names back means the token and role work. A Connected status only tells you Claude Code could start the process, so try one real question before you trust it.

Run it read-only

Add --disable-write after the command to drop every tool that creates or changes something, like dashboard updates, alert rule changes and incident creation:

claude mcp add grafana \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token \
  -- uvx mcp-grafana --disable-write

To cut tools you don't use, which also saves context, pass --disable-<category>, for example --disable-oncall. Some categories are off by default, including cloudwatch, elasticsearch, admin and runpanelquery. Turn them on with --enabled-tools, which replaces the default list, so include the categories you still want.

Keep the token out of the config

claude mcp add writes the token as plain text into ~/.claude.json. To keep it in your shell environment instead, use add-json with a placeholder:

export GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_your_token

claude mcp add-json grafana '{"type":"stdio","command":"uvx","args":["mcp-grafana"],"env":{"GRAFANA_URL":"https://myinstance.grafana.net","GRAFANA_SERVICE_ACCOUNT_TOKEN":"${GRAFANA_SERVICE_ACCOUNT_TOKEN}"}}'

The single quotes keep ${GRAFANA_SERVICE_ACCOUNT_TOKEN} as a placeholder, and Claude Code fills it in from your environment when it starts the server. Run claude mcp get grafana and the token shows as the placeholder, not the value.

This is also the version to commit if you want the whole team on the same Grafana server: add -s project and it goes into .mcp.json without anyone's token in it.

Troubleshooting

If claude mcp get grafana shows "Failed to connect" with ENOENT: Executable not found in $PATH: "mcp-grafana", Claude Code can't find the binary. Use the full path, like ~/go/bin/mcp-grafana, or install uv and use uvx mcp-grafana.

If the server connects but tool calls return 401 or 403, check the token and the service account role. A deleted or expired token fails the same way.

If datasource tools fail with a 404, check your Grafana version. Anything below 9.0 is missing the API they use.

For more detail, add -debug to the server args. It logs every HTTP request and response between mcp-grafana and the Grafana API.

The server also sends anonymous usage stats to Grafana Labs by default, like which tools were called and how many failed. The README says queries, log lines and credentials are never sent. To turn it off, add -e GRAFANA_USAGE_STATS=disabled.

References

Other on-call MCP setups on this blog: Datadog, PagerDuty and Sentry.

Final check

Create a Grafana service account token, then run claude mcp add grafana -e GRAFANA_URL=... -e GRAFANA_SERVICE_ACCOUNT_TOKEN=... -- uvx mcp-grafana, with the name before the -e flags. Add --disable-write for read-only access, and ask Claude for a real dashboard to confirm the token works.