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.

Related MCP server: Grafana FastMCP Server

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 delete_folder refuses if a protected folder is nested inside. Anything that cannot be resolved is refused.

• GRAFANA_DATASOURCE_ALLOWLIST — restrict which datasources query_datasource may hit.

• GRAFANA_DRY_RUN — validate and log writes without executing them.

• GRAFANA_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).

• Interactive confirmation — when the client supports MCP elicitation, deleting a dashboard/folder/annotation prompts the human to approve before it runs. The prompt shows the tool, the exact arguments and a fingerprint; the target's version is pinned across the prompt and the action is refused if it changed; a prompt nobody answers is a refusal. Clients that can't elicit fall back to the GRAFANA_ALLOW_DELETE gate.

• GRAFANA_REQUIRE_HUMAN_APPROVAL — default false. When true, deletes are refused if the client cannot elicit (instead of falling back to the GRAFANA_ALLOW_DELETE gate alone).

• Secrets are never returned — datasource secureJsonData, passwords and tokens are stripped from every response.

See SECURITY.md.

Working with dashboards & queries

Conventions for the dashboard JSON model, panel/target shapes, PromQL/LogQL/SQL query patterns, folder organisation and safe editing live in the bundled skill: .claude/skills/grafana-dashboards-and-queries/SKILL.md. Agents that load it can build and edit dashboards to a consistent standard without being re-taught each time.

Developing

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

Licence

MIT