mcp-grafana

Requirements

• Grafana version 9.0 or later is required for full functionality. Some features, particularly datasource-related operations, may not work correctly with earlier versions due to missing API endpoints.

Quick Start

Requires uv. Add the following to your MCP client configuration (e.g. Claude Desktop, Cursor):

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

For Grafana Cloud, replace GRAFANA_URL with your instance URL (e.g. https://myinstance.grafana.net). See Usage for more installation options including Docker, binary, and Helm.

Query Examples

Note: Query examples tools are disabled by default. To enable them, add examples to your --enabled-tools flag.

• Get query examples: Retrieve example queries for different datasource types to learn query syntax.

Usage

This MCP server works with both local Grafana instances and Grafana Cloud. For Grafana Cloud, use your instance URL (e.g., https://myinstance.grafana.net) instead of http://localhost:3000 in the configuration examples below.

1. If using service account token authentication, create a service account in Grafana with enough permissions to use the tools you want to use, generate a service account token, and copy it to the clipboard for use in the configuration file. Follow the [Grafana service account documentation][service-account] for details on creating service account tokens. Tip: If you're not comfortable configuring fine-grained RBAC scopes, a simpler (but less restrictive) option is to assign the built-in Editor role to the service account. This grants broad read/write access that covers most MCP server operations — use it when convenience outweighs strict least-privilege requirements.

Note: The environment variable GRAFANA_API_KEY is deprecated and will be removed in a future version. Please migrate to using GRAFANA_SERVICE_ACCOUNT_TOKEN instead. The old variable name will continue to work for backward compatibility but will show deprecation warnings.

TLS Configuration

If your Grafana instance is behind mTLS or requires custom TLS certificates, you can configure the MCP server to use custom certificates. The server supports the following TLS configuration options:

• --tls-cert-file: Path to TLS certificate file for client authentication
• --tls-key-file: Path to TLS private key file for client authentication
• --tls-ca-file: Path to TLS CA certificate file for server verification
• --tls-skip-verify: Skip TLS certificate verification (insecure, use only for testing)

Example with client certificate authentication:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Example with Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

The TLS configuration is applied to all HTTP clients used by the MCP server, including:

• The main Grafana OpenAPI client
• Prometheus datasource clients
• Loki datasource clients
• Incident management clients
• Sift investigation clients
• Alerting clients
• Asserts clients

Direct CLI Usage Examples:

For testing with self-signed certificates:

./mcp-grafana --tls-skip-verify -debug

With client certificate authentication:

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

With custom CA certificate only:

./mcp-grafana --tls-ca-file /path/to/ca.crt

Programmatic Usage:

If you're using this library programmatically, you can also create TLS-enabled context functions:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

URL validation when wiring your own HTTP server:

When library consumers wire mcp-grafana's context functions into their own http.Server, install ValidateGrafanaURLMiddleware to reject malformed X-Grafana-URL headers with 400 Bad Request (matching the binary's behavior):

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

When calling NewGrafanaClient directly (stdio or programmatic construction), pre-validate untrusted URLs to avoid a reachable panic:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Both patterns share ValidateGrafanaURL as the single validator.

Server TLS Configuration (Streamable HTTP Transport Only)

When using the streamable HTTP transport (-t streamable-http), you can configure the MCP server to serve HTTPS instead of HTTP. This is useful when you need to secure the connection between your MCP client and the server itself.

The server supports the following TLS configuration options for the streamable HTTP transport:

• --server.tls-cert-file: Path to TLS certificate file for server HTTPS (required for TLS)
• --server.tls-key-file: Path to TLS private key file for server HTTPS (required for TLS)

Note: These flags are completely separate from the client TLS flags documented above. The client TLS flags configure how the MCP server connects to Grafana, while these server TLS flags configure how clients connect to the MCP server when using streamable HTTP transport.

Example with HTTPS streamable HTTP server:

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

This would start the MCP server on HTTPS port 8443. Clients would then connect to https://localhost:8443/ instead of http://localhost:8000/.

Docker example with server TLS:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

CLI Flags Reference

The mcp-grafana binary supports various command-line flags for configuration:

Transport Options: - -t, --transport: Transport type (stdio, sse, or streamable-http) - default: stdio - --address: The host and port for SSE/streamable-http server - default: localhost:8000 - --base-path: Base path for the SSE/streamable-http server - --endpoint-path: Endpoint path for the streamable-http server - default: /

Debug and Logging: - --debug: Enable debug mode for detailed HTTP request/response logging - --log-level: Log level (debug, info, warn, error) - default: info

Observability: - --metrics: Enable Prometheus metrics endpoint at /metrics - --metrics-address: Separate address for metrics server (e.g., :9090). If empty, metrics are served on the main server - --slow-request-threshold: Log an event when any MCP request (tool invocation, list, resource read, etc.) takes longer than this duration. Accepts Go duration strings (e.g., 500ms, 5s). Default 0 disables slow-request logging. See the Slow-request logging section. - --slow-request-log-level: Log level for slow-request events (info or warn) - default: warn.

Session Management: - --session-idle-timeout-minutes: Session idle timeout in minutes. Sessions with no activity for this duration are automatically reaped - default: 30. Set to 0 to disable session reaping. Only relevant for SSE and streamable-http transports.

Tool Configuration: - --enabled-tools: Comma-separated list of enabled categories - default: all categories except admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, runpanelquery, and snowflake. To enable disabled categories, add them to the list (e.g., "search,datasource,...,snowflake") - --max-loki-log-limit: Maximum number of log lines returned per query_loki_logs call - default: 100. Note: Set this at least 1 below Loki's server-side max_entries_limit_per_query to allow truncation detection (the tool requests limit+1 internally to detect if more data exists). - --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 (create/update operations) - --disable-loki: Disable loki tools - --disable-elasticsearch: Disable elasticsearch and opensearch tools - --disable-influxdb: Disable InfluxDB tools - --disable-alerting: Disable alerting tools - --disable-dashboard: Disable dashboard 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 tools - --disable-rendering: Disable rendering tools (panel/dashboard image export) - --disable-cloudwatch: Disable CloudWatch tools - --disable-examples: Disable query examples tools - --disable-clickhouse: Disable ClickHouse tools - --disable-snowflake: Disable Snowflake tools - --disable-runpanelquery: Disable run panel query tools - --disable-graphite: Disable Graphite tools - --disable-athena: Disable Athena tools

Health Check Endpoint

When using the SSE (-t sse) or streamable HTTP (-t streamable-http) transports, the MCP server exposes a health check endpoint at /healthz. This endpoint can be used by load balancers, monitoring systems, or orchestration platforms to verify that the server is running and accepting connections.

Endpoint: GET /healthz

Response: - Status Code: 200 OK - Body: ok

Example usage:

```bash