让 Claude Code 直接查询 Grafana 排障

生产环境一出问题，你通常会在 Claude Code 和 Grafana 之间来回折腾：打开 Grafana，找到对应的 dashboard，仔细辨认曲线上的尖峰，复制一条 PromQL 查询或一段 Loki 日志，粘贴到终端里。等 Claude 要求扩大时间范围，你又得再来一遍。最后，你成了指标数据和 Agent 之间一个缓慢、还会丢失信息的复制粘贴中转站。

Grafana MCP 是 Grafana Labs 官方推出的 MCP server。它让 Claude Code 能够自行搜索 dashboard，通过 PromQL 查询 Prometheus、通过 LogQL 查询 Loki，读取告警规则及其触发状态，还能查询事故。它支持自托管的 Grafana 9.0+ 和 Grafana Cloud，并以 Apache 2.0 许可证开源。

可以搭配我们的 Sentry MCP 指南一起使用：Sentry 告诉 Claude 正在发生什么错误，Grafana 则展示错误从什么时候开始，以及前后各项指标的变化。

创建一个具有 Viewer 角色的 Grafana service account token（Administration → Users and access → Service accounts），然后运行：

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

将 <your-token> 替换为你的 token。如果使用 Grafana Cloud，则将 URL 换成你的 Grafana Cloud 地址（https://myinstance.grafana.net）。重启 Claude Code，然后运行 claude mcp list。整个过程大约需要 5 分钟。

⚡ 复制这段 prompt：让 Claude Code 帮你安装并验证

跳过下面的手动步骤，把整个任务交给 Agent：

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.

Agent 无法替你创建 service account token，因此这段 prompt 会让它停下来向你索取。这是有意设计的：token 使用什么角色，由你决定。

更愿意自己动手，不想交给 Agent？下面是手动操作步骤。

确认 uv 可用：

uvx --version

没有可用于测试的 Grafana？用 Docker 启动一个临时的本地实例，然后在 http://localhost:3000 登录，用户名和密码为 admin / admin：

docker run -d --name grafana -p 3000:3000 grafana/grafana

在 Grafana 中，进入 Administration → Users and access → Service accounts，选择 Add service account，为它分配 Viewer 角色，然后点击 Add service account token 并复制 token。之后你就无法再次查看它了。

以后想让 Claude 创建 dashboard 或静默告警？改为给账户分配 Editor 角色，并在第 3 步中去掉 --disable-write。

--scope user 会让它在所有项目中都可用。-- 后面的所有内容都会传给 server，因此 --disable-write 应该放在这里：

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

这是 2026 年 10 月使用 Claude Code 2.1.291 的实际运行结果。server 名称一定要放在 --env 参数之前：如果放在后面，Claude Code 会将它当成另一个环境变量，并报错 Invalid environment variable format 后停止。Connected 表示 server 已启动；只有执行工具调用时，它才会访问 Grafana。

Prometheus、Loki、dashboard、告警和事故相关工具默认启用。其他数据源默认关闭，需要通过 --enabled-tools 启用，例如 sql、cloudwatch、elasticsearch 或 influxdb。你也可以关闭从不使用的类别，比如添加 --disable-oncall，让 Claude 的工具列表保持精简。

Claude Code 查询的，就是你处理事故时查看的那些 dashboard、指标和告警。

验证它是否真的能用

claude mcp list

✔ grafana uvx mcp-grafana –disable-write – Connected

! grafana 401 Unauthorized → token 不正确或已被删除；创建一个新的 token。

✘ grafana Failed to connect → 运行 uvx mcp-grafana --help，查看实际错误。

然后给 Claude 一个实际问题：

Search my Grafana dashboards, pick the one for the API service, and tell me if the error rate changed in the last 6 hours

如果 Claude 先调用 dashboard 搜索工具，再调用 Prometheus 或 Loki 查询工具，并根据你的数据给出实际数字，就说明 token、URL 和数据源访问都正常。

需要避免的常见错误

为了省事，给 token 分配 Admin 角色。持有 Admin token 的 AI Agent 可以删除 dashboard 和告警规则。先从 Viewer 和 --disable-write 开始，只有需要写入工具时再提升权限。

把 server 参数放在 -- 之前。--disable-write 属于 mcp-grafana，不属于 claude mcp add。如果放在双连字符之前，Claude Code 会拒绝或忽略它。

使用旧的 GRAFANA_API_KEY 变量。它仍然可用，但已弃用。新配置应使用 GRAFANA_SERVICE_ACCOUNT_TOKEN。

要求获取整个 dashboard。完整的 dashboard JSON 可能占用大量上下文窗口。改为请求摘要或指定 panel；server 专门提供了处理这类请求的工具。

运行低于 9.0 的 Grafana。数据源工具会报错 400 … “id is invalid”。解决办法是升级 Grafana，而不是重新配置 server。

是的。这个 server 以 Apache 2.0 许可证开源。你需要一个 Grafana 实例，免费的 Grafana Cloud 套餐和自托管的 OSS 安装都可以使用。

支持 Grafana Cloud 吗？

支持。将 GRAFANA_URL 设置为你的 stack 地址，例如 https://myinstance.grafana.net，并使用该 stack 的 service account token。有些工具只在 Cloud 中提供，例如 Sift investigations。

Claude 能修改我的 dashboard 或告警吗？

按照本指南的配置，不能。--disable-write 会移除写入工具，而 Viewer token 本身也没有写入权限。只有希望 Claude 执行编辑操作时，才同时解除这两项限制。

我不用 uv，还有其他运行方式吗？

有。项目还提供 Docker 镜像、预编译二进制文件和 Helm chart。README 的 Usage 部分介绍了每一种方式。

运行 claude mcp remove grafana --scope user，然后在 Grafana 中删除 service account token，防止它被再次使用。

GitHub 上的 grafana/mcp-grafana——包含 README、完整工具列表以及所有 CLI 参数。

Grafana service accounts——介绍如何创建 token 和选择角色。

Claude Code MCP 文档——介绍 claude mcp add 的选项和作用域。

本文最初发布于 quickpromptco.com，该网站会持续更新这份指南。

如需进一步处理，你可以考虑屏蔽此人和／或举报滥用行为。