How do I install Grafana?

Grafana is a local plugin. Install it using npm package: @dockndevai/mcp-grafana and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

Is Grafana safe to use?

Grafana was flagged by MCP Marketplace's security scan, scoring 4.8/10 (high risk). It has 3 high or critical findings to review. Review the security report on this page carefully before installing it.

What credentials does Grafana need?

Grafana requires the following credentials or environment variables: GRAFANA_URL, GRAFANA_TOKEN, GRAFANA_MODE. You can find setup instructions on the server detail page.

What AI apps work with Grafana?

Grafana uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Grafana MCP Server

by dockndevai

Data & AnalyticsUse Caution4.8Local

Free

Search & edit Grafana dashboards, query datasources (PromQL/LogQL/SQL), inspect alerts.

About

Search & edit Grafana dashboards, query datasources (PromQL/LogQL/SQL), inspect alerts.

Security Report

4.8

Use Caution4.8High Risk

This is a well-designed Grafana MCP server that starts read-only, enforces capability, folder, datasource and delete gates, and strips datasource secrets from responses. The main concerns are that laya-guard can send full tool arguments (which may include dashboard JSON) to a configurable URL, that query_datasource advertises a read-only SELECT constraint it does not enforce, and that an elicitation error silently approves destructive operations. Permissions (network_http to the Grafana instance, env_vars for the token) match the server's purpose. Supply chain analysis found 5 known vulnerabilities in dependencies (0 critical, 3 high severity). Package verification found 1 issue.

12 files analyzed · 11 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

What You'll Need

Set these up before or after installing:

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

Environment variable: GRAFANA_URL

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

Environment variable: GRAFANA_TOKEN

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

Environment variable: GRAFANA_MODE

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-dockndevai-mcp-grafana": {
      "env": {
        "GRAFANA_URL": "your-grafana-url-here",
        "GRAFANA_MODE": "your-grafana-mode-here",
        "GRAFANA_TOKEN": "your-grafana-token-here"
      },
      "args": [
        "-y",
        "@dockndevai/mcp-grafana"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

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.

mcp-grafana — safe by default: read-only exposes 11 tools; raising the access mode unlocks writes and (gated) deletes

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

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.
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; clients that can't elicit fall back to the GRAFANA_ALLOW_DELETE gate.
Secrets are never returned — datasource secureJsonData, passwords and tokens are stripped from every response.

Interactive confirmation — the agent asks to delete a dashboard; the server pauses and asks the human via MCP elicitation. Declining leaves the dashboard untouched; approving proceeds.

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