Grafana MCP接入Claude Code：直连仪表盘、指标与告警

生产环境出问题时，传统排查方式往往是这样一套流程：打开 Grafana，找到对应的仪表盘，盯着一根突起的曲线看半天，复制一段 PromQL 查询或者 Loki 日志，粘贴到终端里，等 Claude 追问更宽的时间范围时再来一遍。人成了指标系统和 AI agent 之间一条缓慢、有损的复制粘贴通道。

Grafana MCP 正是为解决这个问题而生。它是 Grafana Labs 官方推出的 MCP 服务器，让 Claude Code 能够自行搜索仪表盘、对 Prometheus 执行 PromQL、对 Loki 执行 LogQL、读取告警规则及其触发状态，甚至查找 incident 记录。它支持自托管的 Grafana 9.0+ 以及 Grafana Cloud，采用 Apache 2.0 开源协议。

Grafana MCP for Claude Code

把它和 Sentry MCP 搭配使用效果更好：Sentry 告诉 Claude 正在发生哪个错误，Grafana 则展示错误从何时开始、以及当时指标处于什么状态。

Grafana MCP 能做什么

Grafana MCP 把 Grafana 的核心能力拆成若干工具组暴露给 Claude Code，每个工具组对应一类可执行的查询动作。

工具组	Claude 能做哪些事
Dashboards	搜索仪表盘、获取精简摘要、用 JSONPath 抽取单个属性、读取每个面板的查询语句
Prometheus	执行即时和范围 PromQL 查询、列出指标与标签名、从直方图计算 p50/p90/p95/p99
Loki	执行 LogQL 日志与指标查询、列出标签、提取检测到的日志模式
Alerting	列出告警规则及其状态（firing、normal、error）、读取通知策略和联系人
Incidents & Sift	搜索 incident，并在 Grafana Cloud 上运行 Sift 检查日志错误模式和慢请求
`--disable-write`	移除所有创建、更新、删除工具，让 agent 只能看不能改

这套工具设计的关键在于克制。--disable-write 参数直接砍掉全部写操作，配合 Viewer 角色 token，Claude 只能读取数据，无法触碰你的仪表盘和告警配置。对于把 AI agent 接入生产监控系统这件事，权限边界比功能多寡重要得多。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年推出的开放协议，用于让大语言模型应用以标准化的方式连接外部工具与数据源。可以把 MCP 理解为 AI 世界的 "USB-C 接口"：模型侧只需实现一次客户端，任何遵循协议的服务器即可被识别和调用。一个 MCP server 通过 stdio、SSE 或 HTTP 等传输方式暴露若干 "工具"（tools）、"资源"（resources）和 "提示模板"（prompts），Claude 在需要时主动发起调用，把结果读入上下文再决定下一步。正是这套协议，让 Claude Code 无需为每个监控后端单独定制插件，就能直接查询 Grafana、Sentry 这类系统。

五分钟完成配置

前置条件

需求项	为什么需要	耗时
Grafana 9.0 或更高版本（自托管或 Cloud）	数据源工具依赖 9.0 才加入的 API 端点	0 分钟
服务账号 token	服务器向 Grafana 认证的方式，只读场景用 Viewer 角色足够	约 2 分钟
已安装 uv	快速启动用 `uvx mcp-grafana` 运行服务器，无需全局安装	约 1 分钟
已安装 Claude Code	调用 Grafana 工具的客户端	0 分钟

创建 token 并接入

在 Grafana 中进入 Administration → Users and access → Service accounts，新建服务账号并赋予 Viewer 角色，然后生成 token 并复制——它只会显示一次。

接着执行：

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 换成 https://myinstance.grafana.net 这类地址。重启 Claude Code 后运行 claude mcp list 确认连接状态。

--scope user 让这个服务器在所有项目中可用。-- 之后的参数会传给服务器本身，--disable-write 正属于这一类。

uv 与 uvx 是 Astral 团队用 Rust 开发的 Python 包管理与运行工具。uvx（等价于 uv tool run）可以在不预先全局安装的情况下，直接从 PyPI 拉取并执行某个包提供的命令行工具，并在隔离的临时环境中解析依赖。对于 MCP 服务器这类 "用完即走" 的小工具，uvx mcp-grafana 意味着不必 pip install、不必操心虚拟环境和版本冲突，升级也只是下次运行时自动拉取最新版。这也是官方推荐用 uvx 而非 pip 启动 mcp-grafana 的原因——安装步骤从 "装 Python 包" 简化为 "确保机器上有 uv"。

让 Claude 自己完成安装

如果不想手动操作，可以直接把安装任务交给 agent。下文这段提示词让 Claude 自行完成安装与验证，其中第 5 步要求它实际调用 Grafana 搜索工具并列出前 5 个仪表盘标题，才算真正完成：

你在这台机器上有 shell 访问权限和 `claude mcp` CLI。以只读模式把 Grafana MCP server（grafana/mcp-grafana）接入 Claude Code，然后报告结果。除非第 5 步确实确认成功，否则不要告诉我已经完成：

1. 运行 `uvx --version`。如果 uv 缺失，用对应系统的官方安装脚本安装后重新检查。
2. 运行 `claude mcp list`。如果已存在 grafana 条目，停止并展示其配置，而不是重复添加。
3. 向我询问两个值：Grafana URL 和服务账号 token。告诉我到 Grafana 的 Administration > Users and access > Service accounts 创建 token，角色选 Viewer。永远不要在对话中回显 token，也不要写入 Claude Code 配置以外的任何文件。
4. 为所有项目添加服务器，只读模式：
   `claude mcp add --scope user --transport stdio grafana --env GRAFANA_URL=<url> --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<token> -- uvx mcp-grafana --disable-write`
5. 运行 `claude mcp list` 确认 grafana 显示 Connected。然后调用 Grafana 搜索工具并列出前 5 个仪表盘标题。

任何步骤失败，把确切的错误和产生它的命令告诉我。数据源工具报 400 "id is invalid" 意味着 Grafana 版本低于 9.0，直接说明而不是重试。不要跳过任何步骤。

Agent 无法替你创建服务账号 token，所以提示词会在这一步停下来向你索要。这是有意为之的：角色权限由你决定。

扩展数据源与验证配置

按需开启额外数据源

Prometheus、Loki、仪表盘、告警和 incident 默认开启。其他数据源需要显式启用，例如 sql、cloudwatch、elasticsearch、influxdb 等，通过 --enabled-tools 参数指定。反过来，也可以用 --disable-oncall 关闭从不使用的类别，让 Claude 的工具列表保持精简——工具越多，模型选错工具的概率越高。

PromQL 与 LogQL 分别是 Prometheus 和 Loki 的查询语言。PromQL 面向时间序列，支持 rate()、histogram_quantile() 这类函数，用于计算错误率、分位数等指标；文中提到的 p50/p90/p95/p99 就是从直方图指标经 histogram_quantile() 聚合得到的。LogQL 面向日志流，既可用标签选择器过滤日志（如 {app="api"} |= "error"），也可用类似 PromQL 的管道语法把日志聚合成指标。Grafana MCP 把这两种查询语言封装成工具，让 Claude 无需理解底层 HTTP API，直接构造查询语句即可。

确认服务真正可用

运行 claude mcp list 后，可能出现三种状态：

✔ grafana — Connected，表示服务器已启动。注意它只有在实际调用工具时才会请求 Grafana。
! grafana — 401 Unauthorized，说明 token 错误或已被删除，需要重新创建。
✘ grafana — Failed to connect，运行 uvx mcp-grafana --help 查看真实错误。

之后给 Claude 一个真实问题来验证链路是否通畅：

搜索我的 Grafana 仪表盘，选出 API 服务对应的那个，告诉我过去 6 小时错误率是否发生变化

如果 Claude 先调用仪表盘搜索工具，再调用 Prometheus 或 Loki 查询工具，最后用你数据中的真实数字作答，说明 token、URL 和数据源访问都正常工作。

五个常见配置陷阱

给 token 管理员权限图省事。 一个持有 Admin token 的 AI agent 可以删除仪表盘和告警规则。从 Viewer 和 --disable-write 起步，只在确实需要写工具时再升级。

把服务器参数放在 -- 之前。 --disable-write 属于 mcp-grafana，不属于 claude mcp add。放在双横线之前，Claude Code 会拒绝或忽略它。

继续使用旧的 GRAFANA_API_KEY 变量。 它仍能工作但已废弃，新配置应使用 GRAFANA_SERVICE_ACCOUNT_TOKEN。

要求返回整个仪表盘。 完整的仪表盘 JSON 会吃掉大量上下文窗口。应请求摘要或指定面板，服务器为此提供了专门的工具。

Grafana 版本低于 9.0。 数据源工具会报 400 … "id is invalid"。解决办法是升级 Grafana，而不是重新配置服务器。

官方资源

grafana/mcp-grafana on GitHub — README、完整工具列表和所有 CLI 参数
Grafana service accounts — 如何创建 token 并选择角色
Claude Code MCP docs — claude mcp add 的选项和作用域

服务器本身是 Apache 2.0 开源，免费使用，只需要一个 Grafana 实例，免费的 Grafana Cloud 套餐或自托管 OSS 均可。Grafana Cloud 用户把 GRAFANA_URL 设为你的 stack 地址即可，部分工具（如 Sift 调查）仅在 Cloud 上提供。移除时执行 claude mcp remove grafana --scope user，并记得在 Grafana 中删除对应的服务账号 token，防止被复用。

把监控数据接进 AI agent 的价值不在于少点几次鼠标，而在于当 Claude 能自己拉取指标、日志和告警状态时，它给出的判断才有数据支撑，而不是停留在猜测。