Skip to main content
Glama
@mgcrea/mcp-grafana

@mgcrea/mcp-grafana

by mgcrea

@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_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.

Related MCP server: mcp-grafana

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

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 format

Publish

pnpm dlx release-it       # bump, commit, tag
git push --follow-tags    # CI publishes to npm + GHCR from the tag

License

MIT

Available Tools

14 tools
grafana_auth_statusGrafana: Auth StatusA
Read-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 DashboardA
Read-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 RulesA
Read-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 AlertsA
Read-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 AnnotationsA
Read-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 DatasourcesA
Read-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 LabelsA
Read-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 SilencesA
Read-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: QueryA
Read-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 LokiA
Read-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 PrometheusA
Read-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: RequestA
Read-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 QueryA
Read-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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      2
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      11
      70 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      12
      46 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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 npm
      MIT