@mgcrea/mcp-grafana
# @mgcrea/mcp-grafana
A [Model Context Protocol](https://modelcontextprotocol.io) server for the
[Grafana HTTP API](https://grafana.com/docs/grafana/latest/developers/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_query` fills in template
variables before sending the query, which `/api/ds/query` will not do for you. It takes them
from `vars`, else the dashboard's saved value, else what the browser would pick: All, or the
first value of a `label_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' `cluster`
variable 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 at `max_line_chars`, and anything else is a table.
- **Summarizes dashboards.** `grafana_get_dashboard` flattens 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=full` is 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
`unavailable` and 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. With `GRAFANA_ORG_ID` set, every data tool refuses on a mismatch.
## Tools
| Tool | What it does | Writes |
| --------------------------- | ------------------------------------------------------------------------------------ | ------ |
| `grafana_auth_status` | URL, version, org, login, effective role and permissions; setup steps when unset | no |
| `grafana_search` | Dashboards and folders by title, tag, folder, starred | no |
| `grafana_get_dashboard` | Summary (variables, panels, queries), one panel's JSON, or the full JSON | no |
| `grafana_run_panel_query` | A panel's queries with variables filled in, and the data they return | no |
| `grafana_query_prometheus` | PromQL, instant or range, through a Prometheus datasource | no |
| `grafana_query_loki` | LogQL log lines or metric queries through a Loki datasource | no |
| `grafana_query` | Raw queries against any datasource, including server-side expressions | no |
| `grafana_list_labels` | Label names or values for Prometheus/Loki, restricted by selector, last hour | no |
| `grafana_list_datasources` | uid, name, type, default — never credentials | no |
| `grafana_list_alerts` | Active alerts from every Alertmanager, most severe first | no |
| `grafana_list_alert_rules` | Rules and their state from Grafana and every datasource ruler | no |
| `grafana_list_silences` | Silences with readable matchers | no |
| `grafana_list_annotations` | Deploys, incidents and alert state changes in a window | no |
| `grafana_request` | GET any `/api/` or `/apis/` endpoint; any method (with `confirm`) when writes are on | gated |
| `grafana_save_dashboard` | Create or update a dashboard; refuses to overwrite a concurrent edit | yes |
| `grafana_delete_dashboard` | Delete a dashboard (`confirm: true`) | yes |
| `grafana_create_annotation` | Mark a moment or region | yes |
| `grafana_create_silence` | Silence alerts matching matchers, for a duration | yes |
| `grafana_expire_silence` | End a silence (`confirm: true`) | yes |
## Configure
| Variable | Required | Description |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `GRAFANA_URL` | yes | Grafana root URL, including any sub-path, e.g. `https://grafana.example.com`. |
| `GRAFANA_SERVICE_ACCOUNT_TOKEN` | one of | A service account token (`glsa_…`). `GRAFANA_API_KEY` is accepted as an alias. |
| `GRAFANA_USERNAME` / `PASSWORD` | one of | Basic auth instead of a token. |
| `GRAFANA_ORG_ID` | no | The org this server must read. Sent as `X-Grafana-Org-Id`; data tools refuse on a mismatch. |
| `GRAFANA_ALLOW_WRITES` | no | `1` to register the write tools. |
| `GRAFANA_HEADERS` | no | Extra headers as JSON, e.g. a Cloudflare Access service token. |
| `GRAFANA_TIMEOUT` | no | Seconds per request. Defaults to 30. |
| `GRAFANA_MAX_RETRIES` | no | Retries on 429/502/503/504 for reads. Defaults to 2. Writes are never retried. |
| `GRAFANA_DEBUG` | no | `1` to log each request to stderr. |
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=1` adds the write tools; the destructive ones
then additionally require an explicit `confirm: true` on every call, and `grafana_request`
requires it for any method but GET.
- **Saves never overwrite.** `grafana_save_dashboard` sends `overwrite: 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 `fetch` throughout.
- **Credentials stay in your environment**, are never echoed back (`grafana_auth_status` lists
header names, not values), and are refused when embedded in `GRAFANA_URL`.
## Quick start
```bash
pnpm install
pnpm build
```
```json
{
"mcpServers": {
"grafana": {
"command": "npx",
"args": ["-y", "@mgcrea/mcp-grafana"],
"env": {
"GRAFANA_URL": "https://grafana.example.com",
"GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_..."
}
}
}
}
```
### Inspect the tools
```bash
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
```bash
pnpm dev # tsdown --watch
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm format
```
### Publish
```bash
pnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tag
```
## License
MIT
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.