Open source Grafana MCP server on Grafana Labs

Introduction to the Grafana MCP server

Thu, 01 Oct 2026 13:22:11 +0000

Introduction to the Grafana MCP server

This article outlines what the open source Grafana MCP server is, what it can do, and how authentication and permissions work.

For Grafana Cloud’s hosted MCP server, refer to Grafana Cloud MCP server.

What you’ll achieve

You understand how the server fits into the Model Context Protocol ecosystem, what kinds of tools it exposes (metrics, logs, traces, dashboards, alerting, and more), and how Grafana RBAC applies.

Before you begin

You will need a Grafana instance (Grafana 9.0 or later) and an MCP-compatible client (for example, Claude Desktop, Cursor, or VS Code with Copilot).

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a standard way for AI assistants and LLM clients to connect to external systems. The Grafana MCP server implements MCP so your client can talk to Grafana without you writing custom integrations. The server exposes tools that map to actions in Grafana such as querying metrics and logs, searching dashboards, managing alert rules, working with incidents and OnCall, and generating deeplinks. Your AI assistant calls these tools on your behalf when you ask questions or give instructions that involve Grafana.

Tools and capabilities

The server exposes many tools, grouped by area: dashboards (search, get summary, get panel queries, update, patch), folders (search, create), datasources (list and query Prometheus, Loki, InfluxDB, ClickHouse, Snowflake, CloudWatch, Google Cloud Logging, Elasticsearch, Pyroscope), Tempo (trace search, metrics, trace diff, attribute exploration), alerting (rules and routing), incidents (Grafana Incident), OnCall (schedules, alert groups), navigation (deeplinks), annotations, snapshots (list, get, create, delete), rendering (panel or dashboard images), and user info (current identity and the organizations it can access). Some tool categories are disabled by default to save context window; you enable them with Enable and disable tools. For dashboards, prefer get_dashboard_summary and get_dashboard_property over get_dashboard_by_uid when you do not need the full JSON, to manage context window use.

Authentication and RBAC

The server uses a Grafana service account token (or username and password) to call the Grafana API. Each tool requires the right Grafana RBAC permissions and scopes. For example, reading dashboards needs dashboards:read and a scope like dashboards:* or dashboards:uid:xyz. Creating or updating dashboards needs dashboards:create and dashboards:write and appropriate folder scopes. You can assign the built-in Editor role to the service account for broad access, or use fine-grained permissions for least-privilege. Grafana Incident uses basic roles (Viewer for read, Editor for write). For full RBAC details, refer to Grafana RBAC.

Next steps

Clients, Set up, and Configure.
MCP tools reference for tools, permissions, scopes, and RBAC guidance.
Client configuration examples.
Guides.

Set up by client

Wed, 29 Jul 2026 17:47:59 +0200

Set up by client

Configure the open source Grafana MCP server for your MCP-compatible client. Each guide lists the config file location and a working server block.

Refer to Client configuration examples and Set up when you need more JSON or install options.

Claude Desktop
Set up the Grafana MCP server for Claude Desktop.
Cursor
Set up the Grafana MCP server for Cursor.
Codex CLI
Set up the Grafana MCP server for the OpenAI Codex CLI.
VS Code and GitHub Copilot
Set up the Grafana MCP server for VS Code with GitHub Copilot agent mode.
Claude Code
Set up the Grafana MCP server for the Claude Code CLI.
Gemini CLI
Set up the Grafana MCP server for the Google Gemini CLI.
Windsurf
Set up the Grafana MCP server for Windsurf.
Zed
Set up the Grafana MCP server for the Zed editor.

Set up the Grafana MCP server

Wed, 29 Jul 2026 17:47:59 +0200

Set up the Grafana MCP server

Choose how you install and run the open source Grafana MCP server. Start with uvx for the least setup, or use Docker, a downloaded binary, or Helm when that fits your environment. Refer to Clients for client-specific steps and Client configuration examples for copy-paste MCP JSON (debug, TLS, and more).

Note
These instructions cover the open source server, which you install and run yourself. If you want to connect an external AI agent to Grafana Cloud without running your own server, refer to Grafana Cloud MCP server instead.

Install with uvx
Run the Grafana MCP server with uvx for a zero-install setup.
Install with Docker
Run the Grafana MCP server using the official Docker image.
Install the binary
Download or build the Grafana MCP server binary.
Deploy with Helm
Deploy the Grafana MCP server to Kubernetes using the Helm chart.
Client configuration examples
Example MCP client JSON for uvx, binary, Docker, VS Code, and debug mode.

Reference

Wed, 29 Jul 2026 17:47:59 +0200

Reference

Technical reference for the open source Grafana MCP server, including the MCP tools permission table.

MCP tools reference
MCP tools, required Grafana RBAC permissions and scopes, and related guidance.

Configure the Grafana MCP server

Wed, 29 Jul 2026 17:47:59 +0200

Configure the Grafana MCP server

Configure the open source Grafana MCP server: how it connects to Grafana, which tools are enabled, and how clients connect to the server.

Authentication
Authenticate the Grafana MCP server to Grafana using a service account token or username and password.
Transports and addresses
Choose how the Grafana MCP server communicates with clients: stdio, SSE, or streamable-http.
Enable and disable tools
Control which MCP tools the Grafana MCP server exposes and use read-only mode.
Client TLS (Grafana connection)
Use TLS certificates when the Grafana MCP server connects to Grafana (mTLS or custom CA).
Server TLS (streamable-http)
Serve the Grafana MCP server over HTTPS when using streamable-http transport.
Multi-organization and headers
Target a specific Grafana organization and send custom HTTP headers from the MCP server.
Command-line flags
CLI flags for the mcp-grafana binary, including transports, tools, TLS, and read-only mode.
Health check endpoint
HTTP health check for SSE and streamable-http transports.

Guides

Thu, 01 Oct 2026 13:22:11 +0000

Guides

Step-by-step use cases for the open source Grafana MCP server: query metrics and logs, search and inspect dashboards, manage alert rules, generate deeplinks, run panel queries, and use Grafana Incident.

Query metrics with Prometheus
Use the MCP server to run PromQL queries against a Prometheus datasource from your AI assistant.
Query logs with Loki
Use the MCP server to run LogQL queries against a Loki datasource from your AI assistant.
Search and inspect dashboards
Use the MCP server to search dashboards and get summaries or panel queries without loading full JSON.
Manage alert rules
Use the MCP server to list, create, update, and delete Grafana alert rules and manage routing.
Generate deeplinks to Grafana
Use the MCP server to create accurate dashboard, panel, and Explore links instead of guessing URLs.
Run a dashboard panel query
Use the MCP server to execute a dashboard panel's query with custom time range and variable overrides.
Use Grafana Incident
Use the MCP server to manage Grafana Incident incidents (list, create, get, add activities, update).
Query metrics with InfluxDB
Use the MCP server to run Flux or InfluxQL queries against an InfluxDB datasource from your AI assistant.

Developer

Wed, 29 Jul 2026 17:47:59 +0200

Developer

Build and test the server from source, use it as a Go library, and run it with Prometheus metrics and OpenTelemetry tracing.

Go SDK (programmatic use)
Use the Grafana MCP server as a Go library to build custom MCP contexts and TLS configuration.
Observability (metrics, tracing, and logs)
Expose Prometheus metrics and OpenTelemetry tracing and logs from the Grafana MCP server.
Build, test, and lint
Run the Grafana MCP server from source, execute tests, and lint the repository.

Anonymous usage statistics

Thu, 01 Oct 2026 13:22:11 +0000

Anonymous usage statistics

The Grafana MCP server can report limited usage statistics about itself to Grafana Labs. Grafana Labs uses this data to improve tools and investigate failures.

To preserve anonymity, the emitted data describes the shape of usage only. Things like tool arguments, resource names, dashboards, queries, log lines, error messages and credentials are never sent, and neither is the Grafana instance’s URL, hostname, stack slug, organisation name or organisation ID.

Nothing an MCP client reports about itself - things like name and version - is collected. Any other value that comes from outside the binary is reduced to a fixed vocabulary before being emitted, so we don’t emit a potentially-identifying value.

Note
Usage statistics reporting is enabled by default. To disable reporting explicitly, refer to Opt out.

Before you begin

Install the Grafana MCP server. Refer to Set up the Grafana MCP server.
Make sure you can change the server’s startup flags or environment variables. If you start the server from an MCP client, refer to Client configuration examples.

Understand which data is collected

Each server process generates one identifier, process_id, as a random UUID in memory when it starts.

Every event carries the following data:

Field	Description	Example
`service`	Always `mcp-grafana`.	`mcp-grafana`
`version`	The version of the `mcp-grafana` binary.	`1.4.2`
`os`	Operating system.	`linux`, `darwin`, `windows`
`arch`	CPU architecture.	`amd64`, `arm64`
`process_id`	A random per-process UID.	UUID
`report_reason`	Why this event was sent: `interval` (once every 4h) or `shutdown`.	`interval`
`process_uptime_ms`	How long the process had been running when the event was built, in milliseconds.	`1234`
`report_seq`	This process’s reports numbered from 1. A gap in the sequence for a `process_id` is a report that was built and never arrived.	`3`
`tools_called`	Comma-separated names of the tools called since the previous event.	`list_datasources,query_prometheus`
`tool_calls`	A nested object keyed by tool name, each holding `calls` and `errors`.	`{"query_prometheus":{"calls":4,"errors":1}}`
`grafana_version`	The version the Grafana instance reported. This is read from a response the server had already fetched for its own reasons, and truncated to 64 bytes. Absent whenever that version is not already known.	`12.1.0`
`target_kind`	`cloud` for Grafana Cloud or `self_hosted` for other hostnames. Grafana Cloud instances reached through custom domains report `self_hosted`.	`cloud`
`auth_method`	The credential category the connection resolved, from a fixed vocabulary.	`service_account_token`
`transport`	The transport the server is running: `stdio`, `sse` or `streamable-http`.	`stdio`
`flags`	The names of the command-line flags that were set. No flag values are sent.	`disable-write,transport`
`env_set`	The names of the configuration environment variables that are set. No free-form values are sent.	`GRAFANA_SERVICE_ACCOUNT_TOKEN,GRAFANA_URL`
`enabled_tools`	The tool category names that are active.	`alerting,dashboard,search`
`disabled_tools`	The tool category names a `--disable-<category>` flag turned off.	`oncall`
`tls_enabled`	Whether the server is serving HTTPS (only the `streamable-http` transport does).	`false`
`metrics_enabled`	Whether the Prometheus `/metrics` endpoint is served.	`true`
`dynamic_multi_org`	Whether per-call organisation selection is enabled.	`false`
`proxied_enabled`	Whether proxied tools from external MCP servers are enabled.	`true`

Server-side enrichment

Reports are received by Grafana’s usage-stats service, the same service that receives usage reports from Grafana, Loki, Mimir and Tempo. On receipt, the service adds two pieces of information derived from the connection rather than from the event:

A coarse geographic region, for example, a country or subdivision, taken from headers added by the CDN edge.
The network organisation name from a whois lookup of the connecting IP address, which typically resolves to your ISP, your cloud provider or your employer’s network.

Inspect what would be sent

To inspect the report, set either the --usage-stats=log flag or the GRAFANA_USAGE_STATS=log environment variable. In this mode, the server prints each event to stderr and doesn’t send it:

GRAFANA_USAGE_STATS=log mcp-grafana

The server prints a report every four hours and on graceful shutdown. To inspect a report sooner, stop the server gracefully after you run the tool calls you want to inspect. If you run the server in a terminal, press Ctrl+C.

Under the stdio transport, stderr goes wherever your MCP client sends the server’s logs. Read the printed events there.

How the report is sent

Property	Value
Destination	`https://stats.grafana.org/mcp-grafana-usage-report`
Method	A single `POST` with the event as a JSON object
Attempts	One. A failed report is never retried and never stored.
Timing	Every four hours, and once more as the process exits
Time limit	One second for the shutdown report, so exit is never delayed longer than that

Because a failed report is never retried, and the counters reset when a report is built rather than when it arrives, a total summed across a process_id is a floor rather than an exact count. report_seq is how a missing report is identified.

To send reports somewhere else, set GRAFANA_USAGE_STATS_ENDPOINT to another URL. This changes the destination only; it is not an opt-out.

Opt out

Use one of the following controls. The --usage-stats flag overrides GRAFANA_USAGE_STATS, and both override DO_NOT_TRACK. Unrecognized mode values disable reporting. Only DO_NOT_TRACK=1 has an effect; other values don’t change the reporting mode.

The controls appear in order of precedence, highest first:

--usage-stats flag: set it to enabled, disabled or log.
shell
```
mcp-grafana --usage-stats=disabled
```
GRAFANA_USAGE_STATS environment variable: set it to enabled, disabled or log.
shell
```
export GRAFANA_USAGE_STATS=disabled
```
DO_NOT_TRACK environment variable: set it to 1 to disable reporting, following the cross-tool DO_NOT_TRACK convention.
shell
```
export DO_NOT_TRACK=1
```

Next steps

To configure other server options, refer to Command-line flags.
To monitor your server, refer to Observability: metrics and tracing.

Troubleshooting

Wed, 29 Jul 2026 17:47:59 +0200

Troubleshooting

Diagnose common problems with the open source Grafana MCP server and Grafana compatibility.

Grafana version compatibility
Datasource errors on Grafana versions earlier than 9.0.