/ 目录 / 演练场 / Grafana MCP
● 官方 grafana 🔑 需要你的密钥

Grafana MCP

作者 grafana · grafana/mcp-grafana

Grafana 官方 MCP——查询 Prometheus/Loki/Tempo、列出 dashboard、获取告警、运行故障时间线,全部通过一个 stdio 服务完成。

Grafana 官方 MCP 服务连接你的 Grafana 实例(OSS、Cloud 或 Enterprise),将数据源和管理 API 封装为 MCP 工具。你可以查询 Prometheus/Loki/Tempo、发现 dashboard、获取告警状态、使用 OnCall 和 Sift 调查——Grafana 能做的,Claude 都能查询。

为什么要用

核心特性

实时演示

实际使用效果

mcp-grafana.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-grafana": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-grafana",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-grafana": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GRAFANA_URL",
          "-e",
          "GRAFANA_API_KEY",
          "mcp/grafana",
          "-t",
          "stdio"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcp-grafana -- docker run -i --rm -e GRAFANA_URL -e GRAFANA_API_KEY mcp/grafana -t stdio

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Grafana MCP

从 Grafana 数据构建故障时间线

👤 SRE/值班工程师 ⏱ ~10 min intermediate

何时使用: 告警刚触发——在接听电话前,你需要一条连贯的时间线。

前置条件
  • Grafana 服务账号 token — Grafana → 管理 → 服务账号;Editor 角色足够用于查询
步骤
  1. 查看正在触发的告警
    Grafana:列出过去 30 分钟内 service=checkout 触发的告警。✓ 已复制
    → list_alerts 返回 1 条或多条带时间戳的告警
  2. 拉取指标
    对每条告警,运行过去 1 小时的底层指标 Prometheus 范围查询,记录超阈值时间点。✓ 已复制
    → query_prometheus_range 返回时序数据
  3. 拉取超阈值时刻的日志
    Loki:查询 service=checkout、level=error,时间窗口 [超阈值时刻-2min, 超阈值时刻+2min],归纳主要错误模式。✓ 已复制
    → 按特征分组的日志行
  4. 整理时间线
    生成简洁时间线:告警触发 → 指标超阈值 → 前 3 个错误日志模式。输出 Markdown,可直接发 Slack。✓ 已复制
    → 时间线可直接粘贴

结果: 在接电话前整理出连贯的故障时间线。

注意事项
  • Loki 查询范围过宽,撑爆 token 预算 — 始终带 service= label;时间窗口要尽量收窄
  • Prometheus 查询的 step 过细 — 1 小时窗口用 step=15s 或 30s
搭配使用: sentry

搞清楚一个 Grafana dashboard 到底展示什么

👤 新入职的团队成员 ⏱ ~15 min beginner

何时使用: 你接手了一个 dashboard,想不逐个点击面板就能理解它。

步骤
  1. 找到 dashboard
    Grafana:搜索标题为「Checkout SLO」的 dashboard。✓ 已复制
    → 返回 Dashboard UID
  2. 检查每个面板
    获取 dashboard。对每个面板,总结:标题、数据源、运行的查询,以及阈值(如有)。✓ 已复制
    → 逐面板说明,包含查询字符串

结果: 整理好 dashboard 的理解文档,可放入 onboarding wiki。

注意事项
  • 变量替换显示异常 — 提醒自己 $service/$env 是 dashboard 运行时插值,MCP 不负责处理

审计告警规则中的噪音

👤 SRE 负责人 ⏱ ~30 min intermediate

何时使用: 季度卫生——找出持续频繁触发或从未触发的规则。

步骤
  1. 拉取规则
    Grafana:列出 Production 文件夹中的所有告警规则。✓ 已复制
    → 带 UID + 表达式的规则列表
  2. 获取触发历史
    对每条,统计过去 30 天的告警实例数,标记出 >100 次(噪音)或 0 次(休眠)的规则。✓ 已复制
    → 每条规则的计数 + 标记集合
  3. 给出建议
    对每条被标记的规则,提出修复方案:收紧阈值、添加 for: 5m,或删除休眠规则。✓ 已复制
    → 每条规则的具体 YAML 修改建议

结果: 具体的清理计划,附 PR-ready 的 YAML。

注意事项
  • 统计实例数 ≠ 统计独立告警 — 按 label 分组;统计独立的触发时段
搭配使用: github

组合

与其他 MCP 搭配,撬动十倍杠杆

mcp-grafana + sentry

交叉关联 Sentry 错误与指标/日志异常

Sentry:获取 OrderService 的错误尖峰。Grafana:拉取同一时间窗口的 Prometheus + Loki 数据。✓ 已复制
mcp-grafana + github

提 PR 清理告警规则

Grafana:审计告警规则。GitHub:提 PR,用收紧后的阈值替换噪音规则。✓ 已复制
mcp-grafana + filesystem

将故障时间线保存为 Markdown 复盘文档

从 Grafana 构建时间线,保存到 /pm/2026-05-incident.md。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_datasources (无) 第一步,了解可用数据源 1 次 API 调用
query_prometheus datasource_uid, query, time? 获取指标即时值 1 次调用
query_prometheus_range datasource_uid, query, start, end, step 时序故障排查 1 次调用
query_loki_logs datasource_uid, expr, start, end, limit? 拉取日志 1 次调用
search_dashboards query: str 查找 dashboard 1 次调用
get_dashboard uid: str 检查面板 1 次调用
list_alert_rules folder? 审计/发现 1 次调用
list_alert_instances state? 查看当前触发的告警 1 次调用
list_oncall_schedules (无) 查询当前值班人员 1 次调用

成本与限制

运行它的成本

API 配额
受限于你的 Grafana 实例限制;Cloud 有组织级 QPS 上限
每次调用 Token 数
300–8000(范围查询可能较大)
费用
开源免费;Grafana Cloud 按正常收费
提示
范围查询始终传 step=;Loki 除非确定数据量,否则用 limit=100

安全

权限、密钥、影响范围

最小权限: 具有 Viewer 或 Editor 权限的服务账号
凭据存储: 服务账号 token 存于环境变量
数据出站: 仅限你的 Grafana URL
切勿授予: 除非需要规则变更,否则不授予 Admin 角色

故障排查

常见错误与修复

401 Unauthorized

token 错误或服务账号已禁用

验证: curl -H 'Authorization: Bearer $TOKEN' $URL/api/health
Prometheus 查询超时

缩短时间范围或增大 step

Loki「parse error」

LogQL 需要在管道左侧有 label 过滤;如 {service="x"} |= "err"

找不到 dashboard

重新导入后 UID 会变;先按标题搜索

替代方案

Grafana MCP 对比其他方案

替代方案何时用它替代权衡
直连 Prometheus MCP只用 Prometheus,没有 Grafana没有 dashboard,没有告警 UI 集成
Datadog MCP你用的是 Datadog不同的可观测性技术栈
Loki MCP 独立版只需要日志功能面更窄

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills