mcp-grafana

Name: mcp-grafana
Author: dockndevai

本地服务

github.com/dockndevai数据与分析13 天前更新

代码仓库

关于 mcp-grafana

mcp-grafana 是面向 Agent 的 Grafana MCP 服务，可搜索仪表板、查询数据源并检查告警。默认只读，并通过分级权限控制编辑与删除。

主要功能

01搜索仪表板与文件夹
02读取仪表板 JSON 模型
03查询 Prometheus、Loki 和 SQL 数据源
04检查告警规则与注释
05按权限模式控制写入和删除
06响应中移除数据源密钥

适用场景

01定位 Grafana 仪表板并查看配置
02通过 PromQL、LogQL 或 SQL 查询数据
03检查告警规则及图表事件
04在获准模式下更新仪表板或添加注释

MCP 相关

该 MCP 服务向客户端提供 Grafana 搜索、读取、查询、告警检查及受权限模式控制的写入工具。默认注册只读工具；删除操作还需管理员模式及显式允许标志。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dockndevai-mcp-grafana": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-grafana"
      ],
      "env": {
        "GRAFANA_URL": "<GRAFANA_URL>",
        "GRAFANA_TOKEN": "<GRAFANA_TOKEN>",
        "GRAFANA_MODE": "<GRAFANA_MODE>"
      }
    }
  }
}

启动命令npx -y @dockndevai/mcp-grafana

需要配置的环境变量

GRAFANA_URLBase URL of the Grafana instance (e.g. http://localhost:3000).

GRAFANA_TOKEN密钥Grafana service-account token (Bearer). Use a Viewer-role account for read-only use.

GRAFANA_MODEAccess mode: read-only | read-write | admin. Starts read-only; writes need read-write.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@dockndevai/mcp-grafana0.3.3stdio

工具

收录的工具列表 · 更新于 3 天前

此工具无需参数。

详细介绍

mcp-grafana

一个默认安全的 Model Context Protocol Grafana 服务。它让 Agent 能够探索和操作 Grafana——搜索仪表板、读取仪表板 JSON 模型、列出和查询数据源（Prometheus / Loki / SQL）、检查告警规则和注释，还可以（在更高权限模式下）创建／更新仪表板和文件夹、写入注释并删除内容。

它是 dockndevai MCP 服务套件的一部分——所有服务共用一种治理模式。

mcp-grafana — 默认安全：只读模式提供 11 个工具；提高访问模式即可解锁写入和（受限的）删除功能

它能为 Agent 提供什么

服务以只读模式启动（参见默认安全）；只有提高模式后，才会注册更高权限的工具。

工具	用途	所需模式
`get_health`	检查实例是否正常运行及其版本	只读
`search`	按名称／标签查找仪表板和文件夹（获取 UID）	只读
`list_dashboards` / `list_folders`	列出仪表板／文件夹	只读
`get_dashboard`	获取完整的仪表板 JSON 模型和元数据	只读
`list_datasources` / `get_datasource`	获取数据源（机密信息会隐藏）	只读
`query_datasource`	通过统一查询 API 运行 PromQL / LogQL / SQL	只读
`list_alert_rules`	获取 Grafana 管理的告警规则	只读
`list_annotations`	获取叠加在图表上的事件	只读
`create_or_update_dashboard`	创建或更新仪表板（有版本记录，可撤销）	读写
`create_folder`	创建文件夹	读写
`create_annotation`	在图表上标记部署／事件	读写
`delete_dashboard` / `delete_folder` / `delete_annotation`	删除（不可撤销）	管理员 + `GRAFANA_ALLOW_DELETE`

安装

npx -y @dockndevai/mcp-grafana

你需要 Grafana 服务账户令牌（Administration → Service accounts → Add service account → Add token）。请授予其可用的最低权限——只读时使用 Viewer，创建／更新时使用 Editor，只有必须删除内容时才使用 Admin。

配置

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_TOKEN": "glsa_...",
        "GRAFANA_MODE": "read-only"
      }
    }
  }
}

有关 Claude Code / Cursor / Codex / VS Code / Windsurf 的配置示例，请参阅 docs/CLIENTS.md；所有支持的变量请参阅 .env.example。

默认安全

访问模型在 src/security.ts 中强制执行，并在服务账号令牌自身角色的基础上提供纵深防御：

GRAFANA_MODE — read-only（默认）→ read-write → admin。只有模式允许其能力时，才会注册工具。只读模式开放 11 个读取工具；编辑需要 read-write；删除需要 admin。
GRAFANA_ALLOW_DELETE — 删除操作不可撤销，因此除了需要 admin 模式外，还必须启用此标志。
GRAFANA_FOLDER_ALLOWLIST / GRAFANA_PROTECTED_FOLDERS — 限定可写入的文件夹；标记可读取但绝不可修改或删除的文件夹（例如 production）。
GRAFANA_DATASOURCE_ALLOWLIST — 限制 query_datasource 可访问的数据源。
GRAFANA_DRY_RUN — 验证并记录写入操作，但不实际执行。
GRAFANA_AUDIT_LOG — 每个受保护操作都会在 stderr 上输出一条 JSON 审计日志（默认开启）。
交互式确认 — 当客户端支持 MCP elicitation 时，删除仪表板／文件夹／注释前，会提示人工批准；不支持 elicitation 的客户端则退回到 GRAFANA_ALLOW_DELETE 限制。
绝不返回机密 — 所有响应都会移除数据源的 secureJsonData、密码和令牌。

交互式确认——Agent 请求删除仪表板；服务暂停操作，并通过 MCP elicitation 请求人工确认。拒绝后仪表板保持不变；批准后继续执行。

参见 SECURITY.md。

使用仪表板和查询

有关仪表板 JSON 模型、面板／目标结构、PromQL/LogQL/SQL 查询模式、文件夹组织和安全编辑的约定，详见随附的技能文件：.claude/skills/grafana-dashboards-and-queries/SKILL.md。加载该文件的 Agent 可以按照统一标准构建和编辑仪表板，无需每次重新讲解。

开发

npm install
npm run build
GRAFANA_URL=http://localhost:3000 GRAFANA_TOKEN=glsa_… node dist/index.js
# introspect without a live Grafana:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | GRAFANA_TOKEN=x node dist/index.js