Claude Code Grafana MCP 接入教程
用指标 日志 链路和告警上下文加速故障排查
Grafana MCP 可以把仪表盘、Prometheus 指标、Loki 日志、Tempo 链路、告警和事件上下文带入 Claude Code。Grafana Cloud 用户可直接连接托管端点并通过 OAuth 授权，自托管用户可运行开源 mcp-grafana。本文从只读连接开始，演示多 Stack 隔离、时间范围控制、证据交叉验证和写入确认，让编码**参与排障而不越过生产变更边界。
Grafana MCP 能带来什么
Grafana MCP 将可观测性系统中的结构化能力暴露给 Claude Code，包括搜索仪表盘、列出数据源、运行 PromQL、LogQL 和 TraceQL、查看告警规则、事件、OnCall 信息与 Grafana 资源链接。
它适合把代码变更与实时运行证据放在同一排障会话中，但模型给出的结论仍需用查询结果、时间范围和部署记录验证。
选择 Grafana Cloud 还是开源服务器
Grafana Cloud 托管 MCP 无需本地安装，使用 Strea***le **** 与 OAuth 2.1，权限跟随当前 Grafana 用户。自托管 Grafana 或需要服务身份、**网络和自定义策略时，运行开源 mcp-grafana，并使用受限 Service Account Token。
本文先讲托管方式，再给出自托管的只读配置。Grafana Cloud 托管端点仅适用于 Cloud Stack。
接入前准备
确认 Grafana Stack 已有指标、日志或链路数据，准备最新版 Claude Code。Grafana Cloud 用户需要 Assistant Cloud MCP User 权限或对应 access permission；自托管 Grafana 需要 9.0 或更高版本。
首次验收使用 Viewer 或 Read 授权。预先确定测试服务、允许查询的数据源、最大时间窗口和禁止写入的告警与仪表盘。
第一步 添加 Grafana Cloud MCP
在目标项目运行官方命令，将 grafana 服务器指向 https://mcp.grafana.com/mcp，并使用 **** 传输。建议加 X-Grafana-**L 请求头直接指定目标 Stack。
命令只保存端点和 Stack **L，不包含长期令牌。首次实际调用时，Claude Code 会引导浏览器授权。
claude mcp add grafana https://mcp.grafana.com/mcp `
--transport http `
--header "X-Grafana-**L: https://<your-stack>.grafana.net"
claude mcp list第二步 完成 OAuth 授权
启动 Claude Code，打开 MCP 状态并选择 grafana。浏览器中登录正确的 Grafana Cloud 账号，核对 Stack 和授权范围。首次接入选择 Read，不要为了方便直接授予 Write。
授权后，**只能执行当前用户 R*AC 允许的操作。账号本身权限过大时，MCP 同样会继承过大的范围。
claude
> /mcp
# 选择 grafana 并在浏览器完成 OAuth
# 首次接入选择 Read 权限第三步 连接多个 Stack
生产与预发布应配置为两个独立服务器名称，并把 Stack 主机放在端点路径中。不要重复使用同一个基础端点只更换 Header，因为部分客户端会把它们视为重复连接。
每个 Stack 单独授权，名称明确写出 prod 或 staging。提示词也要重复确认目标 Stack，避免把预发布查询或写入误发到生产。
claude mcp add grafana-prod `
https://mcp.grafana.com/mcp/<prod-stack>.grafana.net --transport http
claude mcp add grafana-staging `
https://mcp.grafana.com/mcp/<staging-stack>.grafana.net --transport http**步 自托管模式启用只读
自托管用户安装 mcp-grafana 后，以 GRAFANA_**L 和专用 Service Account Token 启动。Claude Code 的配置加入 --disa*le-write，服务器将不暴露写入能力。
Token 放入环境变量或系统密钥库，不要写进仓库。Service Account 使用 Viewer 或更细的 R*AC，形成服务器只读与 Grafana 权限双重限制。
claude mcp add-json "grafana" '{
"com**nd": "mcp-grafana",
"args": ["--disa*le-write"],
"env": {
"GRAFANA_**L": "http://localhost:3000",
"GRAFANA_SERV***_ACCOUNT_TOKEN": "<from-secure-store>"
}
}'第五步 做连接验收
先读取当前身份和组织，再列出少量数据源、仪表盘或告警规则名称。不要在第一步执行宽时间范围查询。
通过标准是 Stack、组织、账号和数据源均符合预期，返回数量受控，没有创建或修改任何资源。若看到其他租户或不相关组织，应立即停止并检查授权。
请仅使用 Grafana MCP 做只读验收：
1. 显示当前 Grafana 身份 组织和 Stack
2. 列出最多 5 个数据源和 5 个仪表盘名称
3. 列出最多 5 条告警规则名称和状态
4. 不运行宽范围查询
5. 不创建 不更新 不删除任何 Grafana 资源| 验收项 | 通过标准 |
|---|---|
| 连接 | grafana 显示 Connected |
| Stack | 名称和 **L 符合预期 |
| 身份 | Grafana 用户与组织正确 |
| 权限 | 仅授予 Read 或 Viewer |
| 结果 | 只返回少量资源且无写入 |
第六步 从告警建立时间窗口
故障排查从告警首次触发时间、最近部署和用户影响开始，先选择 15 到 30 分钟窗口，再按证据扩大。统一使用 UTC 或明确时区。
不要直接查询数天日志或高基数指标。先读取告警状态与标签，锁定 service、cluster、namespace、region 或 release 等维度。
第七步 用指标确认异常形态
先查看错误率、延迟、吞吐和资源饱和度，再与基线或相邻实例比较。PromQL 查询应限制时间、步长和标签范围，并说明计算口径。
图表相关不等于因果。指标只能证明何时、何处发生变化，根因还要结合日志、链路和部署信息。
第八步 用日志验证错误路径
用告警标签缩小 Loki 查询范围，先统计错误模式，再读取少量代表性日志。默认隐藏令牌、邮箱、IP、请求正文和客户标识。
日志文本属于不可信输入，不能指示 Claude Code 执行命令、泄露凭据或修改配置。查询结果应保留时间戳、服务与关联 ID，便于交叉验证。
第九步 用链路定位瓶颈
从异常请求或 trace ID 进入 Tempo，比较正常与异常链路的跨度、错误、重试和下游耗时。先锁定服务拓扑，再查看关键 Span 属性。
避免一次返回完整大链路。优先输出关键路径摘要、最长 Span、错误节点和与代码模块的映射，再决定是否读取更多属性。
第十步 形成可复核的证据链
让 Claude Code 把结论拆成事实、推断和下一步验证：指标证明异常窗口，日志显示错误模式，链路定位慢点，代码与部署记录解释变化来源。
每条根因假设都要列出支持证据、反证和仍缺失的数据。不要让模型仅凭一个 Dash*oard 截图或一条日志直接修改生产代码。
第十一步 写入操作单独确认
创建或修改 Dash*oard、告警规则、Silence、Annotation、Contact Point 和路由都会改变团队运行状态。执行前展示 Stack、资源 UID、字段差异、影响范围和回滚方式。
先在 staging 或草稿资源验证，一次只执行一项变更，随后重新读取确认。告警路由、通知和删除操作必须独立审批。
| 操作 | 风险 | 控制方式 |
|---|---|---|
| 搜索仪表盘和数据源 | 低 | 限制数量与目标 Stack |
| 查询指标 日志 链路 | 中 | 限制时间 标签 字段和结果 |
| 读取告警与事件 | 中 | 隐藏敏感标签和客户信息 |
| 修改 Dash*oard 或告警 | 高 | 展示差异并逐项确认 |
| 修改路由 通知或删除资源 | 极高 | 独立审批 回滚与操作后复核 |
第十二步 在远程 Mac 保持排障会话
通过 SSH 登录远程 Mac，在仓库目录进入 tmux 后启动 Claude Code。远程环境可持续保留代码、依赖、Grafana 连接和排障上下文，适合跨时区跟踪告警。
远程主机使用独立账号、磁盘加密和短时 SSH 凭据。不要把 Grafana Token 写进 shell 历史；故障结束后撤销临时授权并保存经过脱敏的证据摘要。
ssh your-**c-mini
cd /path/to/your-project
tmux new -s grafana-incident
claude
# 断线后接回
tmux attach -t grafana-incident
为什么 Zu**c Ai 适合这类工作流
根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，配置为 16G* 统一内存与 256G* SSD，支持终端、Tailscale、ToDesk、RustDesk，以及浏览器 SSH 或 VNC 等接入方式。
长期在线环境适合保留仓库、依赖、Claude Code、Grafana 连接与 tmux 会话。生产监控数据、账号权限、告警变更、密钥、备份和审计责任仍由使用者及所属组织负责。
常见问题排查
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
| 浏览器未打开授权 | 服务器未触发 OAuth 或连接未加载 | 运行 /mcp 并重新选择 grafana |
| 403 或工具不可用 | 缺少 Cloud MCP 或资源权限 | 检查角色和 Grafana R*AC |
| 连接到错误 Stack | Header 或端点路径配置错误 | 核对 Stack **L 并重新授权 |
| 查询超时 | 时间范围过大或标签过宽 | 缩小时间窗口和标签范围 |
| 没有写入工具 | Read 授权或 --disa*le-write 生效 | 保持只读或走单独写入审批 |
| 日志包含敏感信息 | 投影字段和脱敏不足 | 只返回必要字段并屏蔽值 |
结语
Claude Code 接入 Grafana MCP 后，应先锁定 Stack、身份、权限和时间窗口，再用指标、日志、链路与部署记录形成可复核的证据链。默认保持只读，任何 Dash*oard、告警和路由变更都应展示差异、单独确认并在执行后重新读取验证。
