dockndevai/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.
| Tool | For | Needs mode |
|---|---|---|
| get_health | check the instance is up, version | read-only |
| search | find dashboards & folders by name/tag (get UIDs) | read-only |
| list_dashboards / list_folders | enumerate dashboards / folders | read-only |
| get_dashboard | the full dashboard JSON model + meta | read-only |
| list_datasources / get_datasource | datasources (secrets redacted) | read-only |
| query_datasource | run PromQL / LogQL / SQL via the unified query API | read-only |
| list_alert_rules | Grafana-managed alert rules | read-only |
| list_annotations | events overlaid on graphs | read-only |
| create_or_update_dashboard | upsert a dashboard (versioned, reversible) | read-write |
| create_folder | create a folder | read-write |
| create_annotation | mark a deploy/incident on graphs | read-write |
| delete_dashboard / delete_folder / delete_annotation | delete (irreversible) | admin + GRAFANA_ALLOW_DELETE |
Install
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
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.
- **GRAFANA_DATASOURCE_ALLOWLIST** — restrict which datasources query_datasource may hit.