Configure the Grafana MCP server on Grafana Labs

Authentication

Thu, 23 Apr 2026 10:03:11 +0200

Authentication

The Grafana MCP server needs credentials to call the Grafana API. Use a service account token (recommended) or a username and password.

What you’ll achieve

You set the environment variables (or equivalent) so the server can authenticate to your Grafana instance. The same credentials apply whether you run the server with uvx, Docker, a binary, or Helm.

Before you begin

A Grafana instance (Grafana 9.0 or later).
For token auth: a service account with a token and the RBAC permissions needed for the tools you use.

Use a service account token

Set GRAFANA_URL and GRAFANA_SERVICE_ACCOUNT_TOKEN in the environment passed to the server.

GRAFANA_URL: Your Grafana base URL (for example, http://localhost:3000 or https://myinstance.grafana.net).
GRAFANA_SERVICE_ACCOUNT_TOKEN: The token you created for the service account.

The deprecated GRAFANA_API_KEY is still supported but will be removed in a future version; use GRAFANA_SERVICE_ACCOUNT_TOKEN instead.

Use username and password

You can use basic auth by setting GRAFANA_USERNAME and GRAFANA_PASSWORD instead of a token. This is less suitable for automation; prefer a service account token when possible.

Next steps

Enable and disable tools to control which MCP tools are available.
Transports and addresses for stdio, SSE, and streamable-http.

Transports and addresses

Thu, 23 Apr 2026 10:03:11 +0200

Transports and addresses

The Grafana MCP server supports three transports: stdio (default for local use), SSE, and streamable-http. Choose the one that matches how your MCP client connects.

What you’ll achieve

You run the server with the right transport and, for SSE or streamable-http, the correct address and path so your client can connect.

Before you begin

The server installed (for example, Install with uvx or Install with Docker).

Use stdio transport

With stdio (the default when you run the binary or uvx), the server talks to the client over standard input and output. Use this when the client launches the server as a subprocess (for example, Claude Desktop, Cursor). No --address or port is needed.

mcp-grafana
# or
uvx mcp-grafana

Use SSE or streamable-http transport

With -t sse or -t streamable-http, the server listens on an address (default localhost:8000). Use --address to change host and port, and optionally --base-path or --endpoint-path for path configuration.

mcp-grafana -t sse
mcp-grafana -t streamable-http --address :9090

Clients connect to the server URL (for example, http://localhost:8000/sse for SSE). For streamable-http, the default endpoint path is /mcp (override with --endpoint-path if your client expects a different path).

Next steps

Server TLS (streamable-http) if you need HTTPS for the MCP server.
Client TLS if Grafana is behind mTLS or custom certificates.

Enable and disable tools

Thu, 23 Apr 2026 14:05:09 +0000

Enable and disable tools

You can limit which tools the server exposes (to reduce context window use or lock down capabilities) and run the server in read-only mode.

What you’ll achieve

You enable only the tool categories you need, or disable write operations globally with --disable-write.

Before you begin

The server installed and configured (Set up and Authentication).

Enable optional tool categories

Some tool categories are disabled by default:

runpanelquery – Run dashboard panel queries.
examples – Query examples for datasource types.
clickhouse – ClickHouse datasource tools.
cloudwatch – CloudWatch tools.
searchlogs – Search logs across ClickHouse and Loki.
elasticsearch – Elasticsearch query tool.
influxdb – InfluxDB query tool (Flux and InfluxQL).
admin – Admin tools (teams, users, roles, permissions).

--enabled-tools replaces the default list, so to add an optional category you must pass the full set. For example, to keep the defaults and also enable runpanelquery and examples:

mcp-grafana --enabled-tools search,datasource,incident,prometheus,loki,alerting,dashboard,folder,oncall,asserts,sift,pyroscope,navigation,proxied,annotations,rendering,runpanelquery,examples

Refer to Command-line flags for the default list.

Disable tool categories

Use --disable-<category> to turn off a whole category (for example, --disable-oncall, --disable-alerting, --disable-dashboard). For every flag, read-only behavior, and TLS-related flags, refer to Command-line flags.

For tools that come from external MCP servers through Grafana (for example from Grafana Tempo), refer to Proxied tools.

Run in read-only mode

Use --disable-write to disable all write operations. The server can still read dashboards, run queries, and list resources, but it cannot create or update dashboards, incidents, alert rules, annotations, or investigations.

Next steps

Introduction for an overview of tools and RBAC.
Configure authentication if you have not set credentials yet.

Client TLS (Grafana connection)

Thu, 23 Apr 2026 10:03:11 +0200

Client TLS (Grafana connection)

If your Grafana instance uses mTLS or a custom CA, configure the MCP server to use the correct certificates when it calls the Grafana API.

What you’ll achieve

The server uses your client certificate and key (and optionally a CA file) for HTTPS requests to Grafana, or verifies Grafana’s server certificate with a custom CA.

Before you begin

Client certificate and key (and CA file if needed) for your Grafana endpoint.
The server installed (binary or Docker with access to the cert files).

Configure client TLS

Use these flags when starting the server:

–tls-cert-file – Path to the client certificate file.
–tls-key-file – Path to the client private key file.
–tls-ca-file – Path to the CA certificate file for server verification.
–tls-skip-verify – Skip TLS verification (insecure; use only for testing).

Example:

mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt

With Docker, mount the cert directory and pass the paths inside the container (for example, /certs/client.crt).

Next steps

Client configuration examples for full MCP JSON (binary and Docker) with TLS flags.
Server TLS (streamable-http) if you want HTTPS for the MCP server itself.
Authentication for Grafana credentials.
Command-line flags for all TLS-related flags.

Proxied tools

Thu, 23 Apr 2026 10:03:11 +0200

Proxied tools

Proxied tools are additional MCP tools that this server does not implement itself. It loads them from an MCP server that sits behind a Grafana datasource, using Grafana’s datasource proxy. Your client still talks only to this MCP server; the extra tools show up alongside the built-in ones.

Today only the Grafana Tempo MCP server is supported as a proxied source. Adding another datasource type for proxied tools requires a change to this server, not Grafana configuration alone.

What you’ll achieve

Enable the MCP server in Grafana Tempo and use --disable-proxied when you want proxied tools disabled.

Proxy the Grafana Tempo MCP Server

Complete authentication to Grafana (GRAFANA_URL and credentials). Do not pass --disable-proxied if you want proxied tools loaded.

Enable Tempo’s MCP server so the proxy path responds (for example query_frontend.mcp_server.enabled in YAML or flag query-frontend.mcp-server.enabled). Refer to the Tempo MCP server documentation.

Add a Tempo datasource in Grafana if you do not already have one.

Tools appear as tempo_<remote-tool-name>. They are not listed in the static MCP tools reference. Use your MCP client to list tools from the server.

Disable proxied tools

Proxied tools are enabled by default on this server. Pass --disable-proxied to disable them. The proxied token in --enabled-tools does not gate proxied tools; only --disable-proxied does. Omitting proxied from --enabled-tools does not disable them.

With stdio transport, proxied tools are discovered once at startup. With SSE or streamable-http, discovery runs per MCP session when tools are listed or called.

Next steps

Server TLS (streamable-http)

Thu, 23 Apr 2026 10:03:11 +0200

Server TLS (streamable-http)

When you use the streamable-http transport, you can serve the MCP server over HTTPS using your own TLS certificate and key.

What you’ll achieve

Clients connect to the server with https:// instead of http://. This is separate from client TLS, which configures how the server connects to Grafana.

Before you begin

A TLS certificate and private key for the host and port where the server will listen.
The server run with -t streamable-http.

Configure server TLS

Use these flags with streamable-http:

–server.tls-cert-file – Path to the server TLS certificate file.
–server.tls-key-file – Path to the server TLS private key file.

Example:

mcp-grafana -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  --address :8443

Clients then connect to https://localhost:8443 with the streamable-http path (default --endpoint-path is /mcp, for example https://localhost:8443/mcp).

Next steps

Transports and addresses for transport options.
Client TLS (Grafana connection) for TLS toward Grafana.

Multi-organization and headers

Thu, 23 Apr 2026 10:03:11 +0200

Multi-organization and headers

You can point the server at a specific Grafana organization and add custom HTTP headers to every request to Grafana.

What you’ll achieve

All Grafana API calls use the chosen organization context, and any extra headers you need (for example, tenant or custom auth) are sent automatically.

Before you begin

A Grafana instance with multiple organizations (or a need for custom headers).
The server configured with Authentication.

Set the organization

Set GRAFANA_ORG_ID to the numeric organization ID. The server sends X-Grafana-Org-Id on all requests to Grafana.

When using SSE or streamable-http, you can also send X-Grafana-Org-Id from the client; the header takes precedence over the environment variable so you can override the default org per request.

Send custom headers

Set GRAFANA_EXTRA_HEADERS to a JSON object mapping header names to values. These headers are added to every Grafana API request.

Example:

"GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"value\", \"X-Tenant-ID\": \"tenant-123\"}"

Next steps

Authentication for Grafana credentials.
Enable and disable tools to limit which tools are available.

Command-line flags

Thu, 23 Apr 2026 14:05:09 +0000

Command-line flags

The mcp-grafana binary accepts flags for transports, tools, TLS, and observability. Run mcp-grafana --help for the exact list in your installed build.

What you’ll achieve

You can look up defaults, choose --disable-* flags, or configure TLS without reading the source.

Before you begin

You need a way to run mcp-grafana on your machine—for example, a release binary, uvx, or a container.

Configure transport and HTTP options

-t / --transport: Transport type (stdio, sse, or streamable-http). Default: stdio.
--address: Host and port for the SSE or streamable-http server. Default: localhost:8000.
--base-path: Base path for the SSE or streamable-http server.
--endpoint-path: HTTP path for the streamable-http MCP endpoint. Default: /mcp.
--session-idle-timeout-minutes: Idle timeout for streamable-http sessions, in minutes. Sessions with no activity for this duration are automatically reaped. Set to 0 to disable. Default: 30.

Configure debug and logging

--debug: Enable debug mode for detailed HTTP request and response logging to and from the Grafana API.
--log-level: Log level (debug, info, warn, error). Default: info.

Configure observability endpoints

--metrics: Expose a Prometheus metrics endpoint at /metrics (SSE and streamable-http only).
--metrics-address: Optional separate listen address for metrics (for example, :9090). If empty, metrics are served on the main HTTP server.

Configure tool categories

--enabled-tools: Comma-separated list of enabled tool categories. The default is exactly:

search,datasource,incident,prometheus,loki,alerting,dashboard,folder,oncall,asserts,sift,pyroscope,navigation,proxied,annotations,rendering

Categories not in that default string are off until you add them, including: admin, elasticsearch, cloudwatch, examples, clickhouse, influxdb, searchlogs, and runpanelquery. Pass a full comma-separated list to replace the default entirely, or use --disable-* flags to turn off pieces of the default set.
--disable-search: Disable search tools.
--disable-datasource: Disable datasource tools.
--disable-incident: Disable incident tools.
--disable-prometheus: Disable Prometheus tools.
--disable-write: Disable write tools (read-only mode; refer to the following section).
--disable-loki: Disable Loki tools.
--disable-elasticsearch: Disable Elasticsearch tools.
--disable-influxdb: Disable InfluxDB tools.
--disable-alerting: Disable alerting tools.
--disable-dashboard: Disable dashboard tools.
--disable-folder: Disable folder tools.
--disable-oncall: Disable OnCall tools.
--disable-asserts: Disable Asserts tools.
--disable-sift: Disable Sift tools.
--disable-admin: Disable admin tools.
--disable-pyroscope: Disable Pyroscope tools.
--disable-navigation: Disable navigation (deeplink) tools.
--disable-rendering: Disable rendering tools (panel or dashboard image export).
--disable-cloudwatch: Disable CloudWatch tools.
--disable-examples: Disable query examples tools.
--disable-clickhouse: Disable ClickHouse tools.
--disable-searchlogs: Disable search logs tools.
--disable-runpanelquery: Disable run panel query tools.
--disable-annotations: Disable annotation tools.
--disable-proxied: Disable proxied tools (tools from external MCP servers).

Configure tool limits

--max-loki-log-limit: Maximum number of log lines returned per query_loki_logs call.

Run in read-only mode

--disable-write prevents write operations to Grafana. Use it with read-only service accounts, safer production assistants, or to avoid accidental changes.

When enabled, the following writes are disabled:

Dashboard tools

update_dashboard

Folder tools

create_folder

Incident tools

create_incident
add_activity_to_incident

Alerting tools

alerting_manage_rules (create, update, delete)

Annotation tools

create_annotation
update_annotation

Sift tools

find_error_pattern_logs (creates investigations)
find_slow_requests (creates investigations)

Read operations (queries, lists, searches) stay available.

Configure client TLS for Grafana

--tls-cert-file: Client certificate for mTLS to Grafana.
--tls-key-file: Client private key.
--tls-ca-file: CA certificate for verifying Grafana’s server certificate.
--tls-skip-verify: Skip TLS verification (insecure; testing only).

Configure server TLS for streamable-http

These flags secure the MCP HTTP server (between your MCP client and mcp-grafana), not the connection from mcp-grafana to Grafana:

--server.tls-cert-file: Server certificate for HTTPS.
--server.tls-key-file: Server private key.

Print version information

--version: Print the version and exit.

Next steps

Health check endpoint

Thu, 23 Apr 2026 10:03:11 +0200

Health check endpoint

When you use the SSE (-t sse) or streamable HTTP (-t streamable-http) transport, the MCP server exposes a health check at /healthz. Load balancers, monitoring, and orchestration can use it to verify that the server is running and accepting connections.

What you’ll achieve

You can probe readiness from scripts or upstream checks when the server uses an HTTP transport.

Before you begin

The server running with -t sse or -t streamable-http (not stdio).

Send a health check request

Endpoint: GET /healthz

Response:

Status code: 200 OK
Body: ok

Examples:

# For streamable HTTP or SSE transport with default listen address (localhost:8000)
curl http://localhost:8000/healthz

# With custom address
curl http://localhost:9090/healthz

Note: The health check endpoint is only available when using SSE or streamable HTTP transports. It is not available with the stdio transport (-t stdio), because stdio does not start an HTTP server.