mcp-grafana

A safe-by-default Model Context Protocol server for Grafana. It lets an agent explore and operate Grafana — search dashboards, read the dashboard JSON model, list and query datasources (Prometheus / Loki / SQL), inspect alert rules and annotations, and (in higher modes) create/update dashboards and folders, write annotations, and delete.

Part of the dockndevai MCP server suite — one governance model across all of them.

What it gives an agent

The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Install

npx -y @dockndevai/mcp-grafana

You need a Grafana service account token (Administration → Service accounts → Add service account → Add token). Give it the least role that works — Viewer for read-only use, Editor to create/update, Admin only if you must delete.

Configure

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

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Safe by default

The access model is enforced by src/security.ts — defence in depth on top of the service-account token's own role:

• GRAFANA_MODE — read-only (default) → read-write → admin. A tool is registered only if the mode allows its capability. Read-only exposes the 11 read tools; edits need read-write; deletes need admin.
• GRAFANA_ALLOW_DELETE — deletes are irreversible, so on top of admin mode they also require this flag.
• GRAFANA_FOLDER_ALLOWLIST / GRAFANA_PROTECTED_FOLDERS — confine which folders can be written to; mark folders (e.g. production) that may be read but never modified or deleted. Matched by folder UID or title. Writes check the target folder and, when overwriting, the folder the dashboard currently sits in; create_annotation checks the folder of the dashboard it attaches to; deletes resolve the target's folder first. The General (root) folder is scoped like any other (name it General in the allowlist or protected list). A protected folder also protects its sub-folders, and `dele

... View full README on GitHub