@mgcrea/mcp-grafana
Provides read-only tools for the Grafana HTTP API: searching and summarizing dashboards, running panel queries with template variables resolved, inspecting datasources and auth status, and reading alerts, alert rules, silences, and annotations. Optional write tools support saving/deleting dashboards, creating annotations, and managing silences.
Supports PromQL instant and range queries and label name/value discovery through Grafana's Prometheus datasources, plus reading alert rules from Prometheus rulers when available.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@mgcrea/mcp-grafana Run the CPU usage panel on the Kubernetes dashboard"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@mgcrea/mcp-grafana
A Model Context Protocol server for the Grafana HTTP API: dashboards and the data their panels show, PromQL and LogQL through Grafana's datasources, alerts, alert rules, silences and annotations, shaped to fit a context window.
The server is read-only by default. The write tools are not merely refused when writes are off — they are never registered, so an agent cannot call them at all.
What it does that the API does not
Runs a panel the way the dashboard does.
grafana_run_panel_queryfills in template variables before sending the query, which/api/ds/querywill not do for you. It takes them fromvars, else the dashboard's saved value, else what the browser would pick: All, or the first value of alabel_values(...)query, or""("None") when that query has no values. That last case is common, not an edge: provisioned dashboards (every kube-prometheus-stack mixin) are saved with no current values, and on a single-cluster install the mixins'clustervariable has no values at all. Mixed panels, datasource variables, hidden queries, expressions and library panels are handled. The result says which values were used and what query was sent.Shapes data frames. Grafana answers every datasource in columnar frames: one frame per Prometheus series, each repeating its schema, and Loki log rows that each repeat the full stream label set alongside three UI-only columns. Here, time series come back on one step grid with min/max/avg/last, labels shared by every series or line come back once as
common_labels, log lines are cut atmax_line_chars, and anything else is a table.Summarizes dashboards.
grafana_get_dashboardflattens rows (collapsed, expanded and pre-schema-16), and lists each panel's id, type, unit and queries without the layout and styling: about half the JSON on the kubernetes mixins.view=fullis there for editing.Reads alerting from everywhere it lives. Grafana-managed rules and Grafana's own Alertmanager, plus every Prometheus/Loki datasource's ruler and every Alertmanager datasource. A kube-prometheus-stack install usually has everything in the datasources and nothing in Grafana. A source that does not answer (a Loki with no ruler) shows up in
unavailableand does not fail the call.Says which org it is reading. A service account token is bound to one org and takes no org in the request, so a token copied from the wrong org answers everything with plausible data. The org is shown in the startup banner and in
grafana_auth_status, and stamped on every data response. WithGRAFANA_ORG_IDset, every data tool refuses on a mismatch.
Related MCP server: mcp-grafana
Tools
Tool | What it does | Writes |
| URL, version, org, login, effective role and permissions; setup steps when unset | no |
| Dashboards and folders by title, tag, folder, starred | no |
| Summary (variables, panels, queries), one panel's JSON, or the full JSON | no |
| A panel's queries with variables filled in, and the data they return | no |
| PromQL, instant or range, through a Prometheus datasource | no |
| LogQL log lines or metric queries through a Loki datasource | no |
| Raw queries against any datasource, including server-side expressions | no |
| Label names or values for Prometheus/Loki, restricted by selector, last hour | no |
| uid, name, type, default — never credentials | no |
| Active alerts from every Alertmanager, most severe first | no |
| Rules and their state from Grafana and every datasource ruler | no |
| Silences with readable matchers | no |
| Deploys, incidents and alert state changes in a window | no |
| GET any | gated |
| Create or update a dashboard; refuses to overwrite a concurrent edit | yes |
| Delete a dashboard ( | yes |
| Mark a moment or region | yes |
| Silence alerts matching matchers, for a duration | yes |
| End a silence ( | yes |
Configure
Variable | Required | Description |
| yes | Grafana root URL, including any sub-path, e.g. |
| one of | A service account token ( |
| one of | Basic auth instead of a token. |
| no | The org this server must read. Sent as |
| no |
|
| no | Extra headers as JSON, e.g. a Cloudflare Access service token. |
| no | Seconds per request. Defaults to 30. |
| no | Retries on 429/502/503/504 for reads. Defaults to 2. Writes are never retried. |
| no |
|
The names match Grafana's own mcp-grafana, so swapping is a change of command in an
.mcp.json.
A token needs Viewer for every read tool (with Viewer, the datasource list comes from the
frontend settings, since /api/datasources needs more), Editor for dashboards and
annotations, and whatever your alerting setup requires for silences. grafana_auth_status reports
the role and the permissions the tools depend on.
Security
Read-only by default.
GRAFANA_ALLOW_WRITES=1adds the write tools; the destructive ones then additionally require an explicitconfirm: trueon every call, andgrafana_requestrequires it for any method but GET.Saves never overwrite.
grafana_save_dashboardsendsoverwrite: false, so a dashboard changed since it was read is refused, not clobbered; every save stays in the version history.No runtime dependencies beyond the MCP SDK and Zod — native
fetchthroughout.Credentials stay in your environment, are never echoed back (
grafana_auth_statuslists header names, not values), and are refused when embedded inGRAFANA_URL.
Quick start
pnpm install
pnpm build{
"mcpServers": {
"grafana": {
"command": "npx",
"args": ["-y", "@mgcrea/mcp-grafana"],
"env": {
"GRAFANA_URL": "https://grafana.example.com",
"GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_..."
}
}
}
}Inspect the tools
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'Develop
pnpm dev # tsdown --watch
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm formatPublish
pnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tagLicense
MIT
Available Tools
14 toolsgrafana_auth_statusGrafana: Auth StatusARead-only
Report which Grafana and which organization this server reads, as whom, and what that credential may do: the URL, Grafana version, org id and name, the login (a service account or a user), its effective role and permissions, and whether write tools are registered. When the server is not configured, says exactly what to set. Call this first when a tool you expected is missing, and before trusting data from an instance you have not checked: a service account token picks its org silently.
Inputs: no named parameters.
grafana_get_dashboardGrafana: Get DashboardARead-only
Read a dashboard. view=summary (default) returns what is on it without the layout: variables, and every panel (rows flattened) with its id, type, unit and queries — the layout, styling and overrides left out, typically half the JSON. view=panel returns one panel's full JSON (needs panel_id). view=full returns the whole dashboard JSON with its version, which is what grafana_save_dashboard needs back; it can be tens of KB. To see the DATA a panel shows, use grafana_run_panel_query instead of reading its query and re-typing it.
Inputs: uid (required), view, panel_id.
grafana_list_alert_rulesGrafana: List Alert RulesARead-only
The alert rules and their evaluation state, from Grafana-managed alerting and from every Prometheus/Loki datasource that evaluates its own rules. Firing first, then pending. Each rule has its group, state, health (and lastError when it fails to evaluate), its for and labels; include_query adds the expression. Recording rules are left out unless type=record or all. Use grafana_list_alerts for the alert instances themselves.
Inputs: type, group, limit, state, +4 more.
grafana_list_alertsGrafana: List AlertsARead-only
What is alerting right now: the alerts held by Grafana's Alertmanager and by every Alertmanager datasource, most severe first, with since when, summary and description. Silenced and inhibited alerts are left out unless state=suppressed or all. Labels shared by every alert come back once as common_labels; counts by severity and alertname cover the whole match even when the list is cut.
Inputs: limit, state, search, source, +2 more.
grafana_list_annotationsGrafana: List AnnotationsARead-only
Annotations in a time window, newest first: deploys, incidents and notes people or CI marked on dashboards, and alert state changes (type=alert). Each has its time (and end for a region), text, tags, dashboard and panel. The usual question — "what changed around the spike?" — is a window around the spike with no other filter.
Inputs: to, from, tags, type, +3 more.
grafana_list_datasourcesGrafana: List DatasourcesARead-only
List the datasources: uid, name, type (prometheus, loki, alertmanager, postgres…), and which one is the default. Every query tool takes a datasource by uid or name. Credentials and plugin settings are never returned.
Inputs: type, search.
grafana_list_labelsGrafana: List LabelsARead-only
Discover what to query, for a Prometheus or Loki datasource: with no label, the label names in use; with label, the values it takes (label=name lists Prometheus metric names). Restrict with selector to the series or streams that matter, e.g. the pods of one namespace. Looks at the last hour unless start is given — the datasource default is its whole retention, which returns everything that ever existed.
Inputs: end, label, limit, start, +3 more.
grafana_list_silencesGrafana: List SilencesARead-only
The silences in Grafana's Alertmanager and every Alertmanager datasource: id, state, matchers, start and end, who created it and why. Expired silences are left out unless state=expired or all.
Inputs: limit, state, search, source.
grafana_queryGrafana: QueryARead-only
Run raw queries against any datasource through /api/ds/query — for datasources with no dedicated tool (SQL, Elasticsearch, Tempo, CloudWatch…), or for server-side expressions over other queries ({"datasource": "__expr__", "type": "math", "expression": "$A / $B"}). Each query is the target object as it appears in a panel's JSON (grafana_get_dashboard view=panel shows one). Prefer grafana_query_prometheus / grafana_query_loki for those two, and grafana_run_panel_query to reproduce a panel. Dashboard variables are NOT filled in here.
Inputs: queries (required), to, from, sort, +6 more.
grafana_query_lokiGrafana: Query LokiARead-only
Run LogQL through a Loki datasource. A log query ({namespace="api"} |= "error") returns lines newest first, each with its time, level and the labels that differ between lines (the shared ones once, as common_labels), cut at max_line_chars. A metric query (sum by (app) (count_over_time({namespace="api"} |= "error" [5m]))) returns series on a step grid with stats. Always put a label matcher in the selector and keep the range short: Loki scans every line in it. To count, prefer a metric query over fetching lines.
Inputs: expr (required), end, sort, step, +9 more.
grafana_query_prometheusGrafana: Query PrometheusARead-only
Evaluate PromQL through a Prometheus datasource. mode=instant (default) gives the value at one time — the right mode for almost every question, with any window written into the expression (increase(x[24h])). mode=range gives the shape over time on a step grid with min/max/avg/last per series; use view=stats with sort=max to find outliers among many series. Labels shared by every series come back once as common_labels. Aggregate in the expression (sum by, topk) rather than fetching raw series.
Inputs: expr (required), end, mode, sort, +8 more.
grafana_requestGrafana: RequestARead-only
Escape hatch: GET any Grafana HTTP API endpoint the other tools do not wrap — /api/v1/provisioning/alert-rules/, /api/v1/provisioning/contact-points, /api/v1/provisioning/policies, /api/folders, /api/library-elements, /api/teams/search, /api/org/users, /api/dashboards/uid//versions, /apis/dashboard.grafana.app/v2beta1/namespaces/default/dashboards/. The answer is the raw JSON, unshaped, cut at max_chars. Read-only: only GET is ever sent. Prefer the named tools, which shape their output.
Inputs: path (required), params, max_chars.
grafana_run_panel_queryGrafana: Run Panel QueryARead-only
Run a dashboard panel's queries the way the dashboard would, and return the data: template variables ($namespace, ${datasource}) are filled in — from vars, else the value saved with the dashboard, else the variable's first value (or All) as the browser would pick — and the panel's datasource, hidden queries and expressions are respected. Returns the variable values used and each query as sent, so the result can be checked and re-run with other values. Time series come back on a step grid with stats, logs as lines, anything else as a table. The time range defaults to the dashboard's own (often now-1h).
Inputs: uid (required), panel_id (required), to, from, +7 more.
grafana_searchGrafana: SearchARead-only
Find dashboards and folders by title substring, tag, folder or starred state. Returns uid, title, folder, tags and the URL of each; feed a uid to grafana_get_dashboard. With no arguments, lists every dashboard (up to limit).
Inputs: tags, type, limit, query, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly bounded purpose: dedicated Prometheus/Loki query tools, a generic datasource query tool, a panel-reproduction tool, and a raw GET escape hatch are explicitly differentiated. Alert-related tools are also cleanly split into rules, active alerts, and silences, with cross-references guiding selection.
All tools share the `grafana_` prefix and mostly use consistent snake_case verb_noun naming such as `grafana_query_prometheus`, `grafana_list_alerts`, and `grafana_get_dashboard`. Minor deviations like `grafana_auth_status`, `grafana_search`, and `grafana_request` are readable but do not match the dominant verb_noun pattern.
At 14 tools, the set is well-scoped for a Grafana observability server. The tools cover distinct resources and operations without obvious filler, and the count sits comfortably in the typical 3-15 range.
The read/query surface is comprehensive: dashboard search and inspection, panel execution, Prometheus/Loki/generic datasource queries, label and datasource discovery, alerts, annotations, silences, auth status, and a raw GET escape hatch. The main gap is the absence of write operations such as `grafana_save_dashboard` or silence management, even though `grafana_get_dashboard` references saving a dashboard.
Maintenance
Related MCP Connectors
Read-only access to a Lumin project's logs, metrics, uptime checks, alerts and infrastructure.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read-only access to your Infrly services, deploys, logs, metrics and billing.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables assistants to read-only explore and analyze Grafana dashboards and data sources, execute queries against Prometheus and Azure Log Analytics, and run guided investigation workflows.72-
- AlicenseAqualityBmaintenanceEnables agents to explore and operate Grafana by searching and reading dashboards and folders, querying datasources such as Prometheus, Loki and SQL, and inspecting alert rules and annotations. Its safe-by-default access modes gate dashboard and folder creation, editing and deletion behind escalating permission levels.1170 npm1MIT
- AlicenseAqualityBmaintenanceEnables agents to query and explore Prometheus through PromQL, metric and label discovery, alerts, rules, scrape health, and cardinality, while keeping admin writes disabled unless explicitly enabled.1246 npmMIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP clients read access to a Grafana instance for dashboard search and retrieval, datasource inspection, Prometheus queries with metric and label discovery, Loki log queries, and provisioned alert rules and contact points.72 npmMIT