Grafana MCP Server

一个基于 Model Context Protocol（MCP）的服务器，让 AI 助手对 Grafana 中一切已经可见的内容拥有只读访问权限——Prometheus/Loki 指标、ClickHouse/Postgres/MySQL 数据源，以及你的团队已经做好的仪表盘。用自然语言提问，就能得到真实数据支撑的答案。

适用于 Claude Code、Claude Desktop 以及任何兼容 MCP 的客户端。你的项目可以是任何语言的——本服务器独立运行。

工作原理

Your project (any language)     grafana-mcp-server            Grafana            Datasources
┌───────────────────┐          ┌──────────────────┐          ┌──────────┐       ┌────────────┐
│  Claude Code or   │  stdio   │  Builds the      │  HTTPS   │ /api/ds/ │──────>│ Prometheus │
│  Claude Desktop   │────MCP──>│  per-plugin      │────────->│  query   │──────>│ ClickHouse │
│                   │<─────────│  query model     │<─────────│          │──────>│ Postgres … │
└───────────────────┘          └──────────────────┘          └──────────┘       └────────────┘

服务器只与 Grafana 的 HTTP API 通信。Grafana 使用它自己的凭据将查询代理到数据源，因此助手永远不会握有数据库密码；Grafana 用户能看到什么，助手就恰好能看到什么——一件都不会多。所有请求都是只读的（使用 Viewer 凭据即可确保这一点）。

Related MCP server: Grafana MCP Server

环境要求

• Node.js >= 18 或 Docker（仅用于运行这个 MCP 服务器）

• 一个可以登录的 Grafana 账号——Google / SSO / 密码，你的 Grafana 支持什么就用什么。无需管理员权限、无需服务账号、无需 API 令牌：grafana-mcp-server login 会在浏览器中完成你的登录，并把会话交给服务器（见 身份验证）。如果你有服务账号令牌，也同样可用。

• 已安装 Chrome 或 Edge（只用它作为登录窗口，你日常用什么浏览器都无所谓）。如果两者都没有，login 会回退到一种引导方式，让你在默认浏览器里复制 cookie。

快速开始

方案 A：Node.js

1. 克隆并构建

git clone https://github.com/stonoyan04/grafana-mcp-server.git
cd grafana-mcp-server
npm install
npm run build

这会在 dist/main.js 生成编译后的服务器。

2. 登录

GRAFANA_URL=https://grafana.example.com npm run login

如果已安装 Chrome 或 Edge（无论是作为默认浏览器，还是只是装在这台机器上——这几乎覆盖所有人，不管他们日常用什么都），login 会用它的一个专用窗口——一个一次性的独立配置，而非你日常用的那个——打开 Grafana 登录页。像平时一样登录即可。一旦 Grafana 签发会话，该命令就会存储它、将其从该配置中取出、验证并打印：

[grafana-mcp-server] ✓ signed in as jane <jane@example.com>

无需粘贴，无需令牌，配置里不留下任何机密。如果 Grafana 在 Cloudflare Access 后面，你在同一个窗口里也登录一下，那个 cookie 也会一并被捕获。看到 ✓ 之前不要关闭窗口。会话保存在 ~/.grafana-mcp/sessions/<host>.json（权限 600）。

Playwright 只能驱动 Chrome 和 Edge（比如 Arc 完全无法自动化），所以无论你的默认浏览器是什么，login 都用二者之一作为登录窗口——你的默认浏览器永远不会被触碰。只有当 Chrome 和 Edge 都没有安装时，login 才会回退为在默认浏览器中打开 Grafana，并引导你从 DevTools 一次性复制 grafana_session。

为什么用专用窗口，而不是我打开的标签页？ 浏览器绝不会把 cookie 交给命令行工具——这种隔离正是浏览器的要义——所以 login 驱动一个它自己控制的、独立配置的浏览器实例，然后把会话从中取出来。

强制指定浏览器： npm run login -- --browser chrome（或 msedge；或 npx playwright install chromium 之后的 chromium；也可以是某个 Chromium-based 二进制文件的路径）。npm run login -- --paste 不打开浏览器，直接从 stdin 读取 cookie。

3. 配置

Claude Code —— 一条命令，或者等价的 .mcp.json 配置块：

claude mcp add grafana --scope user --env GRAFANA_URL=https://grafana.example.com -- node /home/john/grafana-mcp-server/dist/main.js

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/home/john/grafana-mcp-server/dist/main.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com"
      }
    }
  }
}

Claude Desktop —— 在配置文件里加入同样的配置块：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

注意： 把 /home/john/grafana-mcp-server 替换为你克隆该仓库的实际路径。唯一必需的设置是 GRAFANA_URL——凭据来自 login 存储的会话。添加服务器后请重启客户端。

改用服务账号令牌？ 在 env 里加 "GRAFANA_TOKEN": "glsa_…"，并跳过 login。或者把 GRAFANA_CREDENTIAL_FILE 指向一个保存该令牌的 0600 权限文件；或从启动时的加密管理器注入（例如 charter secret exec … --exec -- node dist/main.js）。

方式 B：Docker

git clone https://github.com/stonoyan04/grafana-mcp-server.git
cd grafana-mcp-server
docker build -t grafana-mcp-server .

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/john/.grafana-mcp:/root/.grafana-mcp",
        "-e", "GRAFANA_URL=https://grafana.example.com",
        "grafana-mcp-server"
      ]
    }
  }
}

在宿主机上运行 login（因为没有浏览器，所以请从 Node 检出目录执行 GRAFANA_URL=… npm run login），并按示例将 ~/.grafana-mcp 以读写方式挂载——容器需要把轮换的会话写回来。或者跳过挂载；如果你有服务账号令牌，直接传入 -e GRAFANA_TOKEN=glsa_… 即可。

为什么用 -i 而不用 -t？ MCP 通过 stdin/stdout 进行 JSON 通信。-i 保持 stdin 打开；TTY（-t）会破坏数据流。

如果 Grafana 在 Cloudflare Access 后面，请先把宿主机上的令牌缓存只读挂载进去——-v /home/john/.cloudflared:/root/.cloudflared:ro——并先在宿主机上运行 cloudflared access login https://grafana.example.com。容器自身无法运行 cloudflared，所以它读取挂载的缓存（或者 CF_ACCESS_TOKEN）；令牌过期时，在宿主机上重新登录一次即可。

4. 发现你的数据源

List the Grafana datasources

每个查询工具都需要数据源的 uid，而且数据源的类型决定用哪个工具——ClickHouse/Postgres/MySQL 用 query_sql，Prometheus/Loki 用 query_metrics。list_datasources 会告诉你这两项。

5. 开始提问

How many messages per Kafka topic were produced in the last 7 days?   → query_metrics on Prometheus
Which dashboards mention "kafka"?                                     → search_dashboards
Show me the panel queries in that dashboard                           → get_dashboard
Run: SELECT count() FROM events WHERE created > now() - INTERVAL 1 DAY → query_sql on ClickHouse

提示： get_dashboard 会返回每个面板背后的原始 SQL / PromQL。复用一个人已经写过且信得过的查询，比从零写一个更好。

工具

服务器提供 6 个只读工具：

list_datasources

列出数据源的 uid、name、type，以及适用哪个查询工具。无参数。

query_sql

通过 Grafana 对 SQL 类数据源运行原生 SQL，返回数据行。

发送到 /api/ds/query 的查询对象会按插件分别构建——grafana-clickhouse-datasource、vertamedia-clickhouse-datasource 以及内置的 Postgres/MySQL/MSSQL 需要的格式各不相同。

query_metrics

执行 PromQL 或 LogQL 表达式。省略 from 则为即时查询。

search_dashboards

get_dashboard

返回各面板（面板行展开），包含每个面板的数据源和原始查询，以及仪表盘的模板变量和默认时间范围。

health

检查连接，并能区分两个认证层：failingLayer: "cloudflare" 表示要运行 cloudflared access login（或重新执行一次 login）；failingLayer: "grafana" 表示存储的会话/凭据失效或权限不足——运行 grafana-mcp-server login 即可。同时报告凭据的身份和能访问的数据源数量。无参数。当其他工具出错时，先调用它。

数据帧会被展平为以字段名称为键的普通行（Prometheus 序列按标签消歧），行数以 GRAFANA_MAX_ROWS 为上限。

命令

npm run login / npm run logout 是从检出目录里执行同样操作的快捷方式。

配置

所有配置都通过环境变量完成。使用 login 时，只需 GRAFANA_URL。

凭据优先级：GRAFANA_TOKEN → GRAFANA_USERNAME+PASSWORD → GRAFANA_SESSION → GRAFANA_CREDENTIAL_FILE → 由 login 保存的会话 → ~/.grafana-mcp-token（如果存在）。

数据源允许列表

"ALLOWED_DATASOURCES": "OsirT4Bnz,Prometheus"

list_datasources 会隐藏其他所有数据源，查询工具也会拒绝使用它们。

身份验证

Grafana：使用你自己的账户登录（login）

grafana-mcp-server login 让你完成登录，并把会话交给服务器。它会通过 Playwright 驱动 Chrome 或 Edge（无论你的默认浏览器是什么，只要已安装，它仅用作登录窗口），在 ~/.grafana-mcp/browser 下专用配置中运行，打开 GRAFANA_URL/login，然后等 你 来登录——Google、GitHub、SAML、LDAP 或普通密码均可；工具不会看到或输入你的凭据。当 Grafana 设置其 grafana_session cookie 时，该工具会：

1. 将会话（如果前面有 Cloudflare Access，还会一并复制 CF_Authorization cookie）复制到 ~/.grafana-mcp/sessions/<host>.json（0600），

2. 从该浏览器配置中删除 Grafana 的 cookie，使服务器成为该会话的唯一持有者，

3. 通过服务器自己的代码路径调用 /api/user，并打印当前登录的是谁。

Playwright 只能驱动 Chrome 和 Edge，而 Arc 根本无法自动化——因此登录窗口始终是 Chrome/Edge，绝不会是你的默认浏览器（它不会被动过）。只有当 Chrome 和 Edge 都没有安装时，login 才会回退为在你的默认浏览器中打开 Grafana，并引导你从 DevTools 复制一次 grafana_session cookie；该路径还会要求你在复制来源标签页中之后退出登录，避免它参与会话轮换的竞争。

从那时起，服务器会自己维持会话有效：当 Grafana 对过期会话返回 401 session.token.rotate 时，服务器调用 POST /api/user/auth-tokens/rotate，以原子方式持久化新 cookie 并重试。因此，会话会持续到 Grafana 的登录生命周期结束（默认 30 天，空闲 7 天）——当 health 显示 failingLayer: "grafana" 时，重新运行 login 即可。

为什么这是推荐路径：不需要 Grafana 管理员。任何能在浏览器中打开 Grafana 的人都可以使用服务器，权限与自己的账户完全相同，撤销访问也与对待任何用户相同。

为什么粘贴的 cookie 通常几分钟内就失效

Grafana ≥ 10 每隔几分钟轮换一次会话 token，而且只有一个客户端能拿到新的 token。如果你在标签页一直开着的情况下从 DevTools 复制 grafana_session，浏览器会先完成轮换，粘贴出来的 cookie 就会在几分钟内失效——这就是典型的“cookie 不好用了”的体验。login 通过把会话移出浏览器来避免这一点；只要之后你在复制来源的标签页中退出登录（或清除 cookie），login --paste 也同样有效，因为服务器会持久化自己的轮换。

Grafana：其他凭据

scripts/verify.sh 会检查这两个层面，并报告该凭据可以访问什么——但绝不会将其打印出来。

Cloudflare Access（可选）

如果 Grafana 位于 Cloudflare Zero Trust 之后，每个请求还需要带 cf-access-token 头，否则边缘会在 Grafana 看到请求之前将其重定向到登录页。服务器会自动处理这一点：

1. 读取 ~/.cloudflared/<主机名>-<audience>-token 中缓存的 JWT（由 cloudflared access login 写入）

2. 如果缺失或过期，则运行 cloudflared access token --app=<GRAFANA_URL>（非交互式）

3. 使用 login 捕获的 CF_Authorization cookie（如果未过期）

4. 回退到 CF_ACCESS_TOKEN

5. 如果边缘返回 302，则丢弃缓存 token 并换新的 重试一次

该 token 是惰性解析的，按请求完成——绝不会在启动时解析一次——因此即将过期的 token 可以自我修复，而不是在客户端重启之前每次调用都失败。安装 cloudflared 是可选的，但强烈推荐：它能让 token 不断自我刷新，持久时间与你的 Cloudflare 登录时长相同；而 login 捕获的 cookie 则随 Cloudflare 的会话策略过期（通常为 24 小时），之后需要再次调用 login。

brew install cloudflared            # macOS; see Cloudflare's docs for Linux
cloudflared access login https://grafana.example.com

Cloudflare 不会让你登录 Grafana。 CF JWT 只证明你可以访问该主机；Grafana 仍需要自己的凭据。返回 302 / HTML 是 Cloudflare；返回 JSON 401 是 Grafana。health 会报告是哪一种。

不在 Cloudflare 后面？设置 GRAFANA_CF_ACCESS=off，或者干脆不安装 cloudflared 即可——找不到 token 时服务器会跳过这一层。

项目结构

src/
  main.ts                        # Entry point — `login` / `logout` commands, or the stdio MCP server
  login.ts                       # Browser sign-in (Playwright over your default Chromium-based browser) → session store
  default-browser.ts             # Detect the default browser (macOS LaunchServices / xdg) and whether it can be driven
  session-store.ts               # ~/.grafana-mcp/sessions/<host>.json, 0600, atomic writes
  grafana-client.ts              # Grafana HTTP client: two auth layers, CF retry, session rotation, datasource cache
  auth.ts                        # Grafana credential resolution (token / basic / session / file / login store)
  cf-token.ts                    # Cloudflare Access token: cache → cloudflared → login cookie → env, lazy + retry
  query-model.ts                 # Per-plugin /api/ds/query bodies (ClickHouse, SQL, PromQL/LogQL)
  allowed-datasources.ts         # Datasource allowlist
  utils/
    frames.ts                    # Data frames → rows
    format-response.ts           # Truncation, error results
  tools/
    list-datasources.tool.ts     # list_datasources
    query-sql.tool.ts            # query_sql
    query-metrics.tool.ts        # query_metrics
    search-dashboards.tool.ts    # search_dashboards
    get-dashboard.tool.ts        # get_dashboard
    health.tool.ts               # health
scripts/
  verify.sh                      # Check both auth layers; list what the credential can see
  mint-token.sh                  # Turn a fresh admin browser session into a service-account token

许可证

MIT