Set up the Grafana MCP server on Grafana Labs

Install with uvx

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

Install with uvx

uv is Astral’s Python package manager and toolchain. uvx runs a command from a published package in an isolated environment, without installing that package globally. It is similar to npx for Node.js.

Use uvx to run the Grafana MCP server without installing a release binary yourself.

What you’ll achieve

You add the server to your MCP client configuration (for example, Claude Desktop or Cursor) and connect to Grafana using a URL and a service account token.

Before you begin

Install uv and ensure uvx is in your $PATH.
Have a Grafana instance (Grafana 9.0 or later) and a service account token.

Add the server to your MCP client

Add the following to your MCP client configuration file. Replace http://localhost:3000 with your Grafana URL if it is different, and YOUR_SERVICE_ACCOUNT_TOKEN with your service account token.

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

For Grafana Cloud, set GRAFANA_URL to your instance URL, for example https://myinstance.grafana.net.

Next steps

Install with Docker if you prefer to run the server in a container.
Configure authentication for service accounts and RBAC.

Install with Docker

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

Install with Docker

Run the Grafana MCP server using the official image from Docker Hub. The image defaults to SSE, but most users will want to use STDIO mode for direct integration with AI assistants like Claude Desktop.

What you’ll achieve

You run the server in a container and connect your MCP client. You can use stdio (typical for Claude Desktop and similar), SSE, streamable HTTP, or streamable HTTP with server TLS.

Before you begin

Docker installed.
A Grafana instance (Grafana 9.0 or later) and a service account token.

Run the server in STDIO mode

For direct integration with AI assistants, most users will want to use STDIO mode. Pass -t stdio and -i so the container keeps stdin open.

Local Grafana:

docker pull grafana/mcp-grafana
docker run --rm -i \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana -t stdio

Grafana Cloud

docker pull grafana/mcp-grafana
docker run --rm -i \
  -e GRAFANA_URL=https://myinstance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana -t stdio

Run the server in SSE mode

In this mode, the server runs as an HTTP server that clients connect to. You must expose port 8000.

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana

Point your client at http://localhost:8000/sse (or your host and port).

Run the server in streamable HTTP mode

In this mode, the server operates as an independent process that can handle multiple client connections. You must expose port 8000 and set -t streamable-http.

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana -t streamable-http

The default MCP path is /mcp (see --endpoint-path). Clients often use http://localhost:8000/mcp.

Run in HTTPS streamable HTTP mode with server TLS certificates

To terminate TLS on the MCP server, mount certificates and set --server.tls-cert-file, --server.tls-key-file, and --address (for example :8443):

docker pull grafana/mcp-grafana
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 \
  --address :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Next steps

Install the binary for a host-installed binary.
Client configuration examples for JSON snippets (including Docker).
Transports and addresses and Server TLS (streamable-http).

Install the binary

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

Install the binary

Install the Grafana MCP server by downloading a release binary or building from source. This gives you a single executable in your $PATH.

What you’ll achieve

You have the mcp-grafana binary available so your MCP client can run it directly (typically in stdio mode).

Before you begin

For source build: a Go toolchain (see Go install).

Download a release

Open the releases page on GitHub.
Download the archive for your platform.
Extract the binary and place it in a directory that is in your $PATH.

Build from source

If you have a Go toolchain installed you can also build and install it from source. Use go install and set GOBIN so the binary is installed where you want it (for example, a directory in your $PATH).

GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Ensure $GOBIN (or $HOME/go/bin) is in your $PATH. Then add the server to your MCP client config with "command": "mcp-grafana" (or the full path if needed).

Next steps

Configure authentication for Grafana credentials.
Deploy with Helm if you run the server on Kubernetes.

Deploy with Helm

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

Deploy with Helm

Deploy the Grafana MCP server on Kubernetes using the Helm chart from the Grafana helm-charts repository.

What you’ll achieve

The server runs in your cluster and can be used by MCP clients that connect to it (for example, via SSE or streamable-http and an Ingress or LoadBalancer).

Before you begin

kubectl and Helm installed.
A Grafana URL and API key (or service account token) for the server to use.

Install the chart

Add the Grafana Helm repo and install the chart. Set grafana.url and grafana.apiKey (or the equivalent for your chart version) to your Grafana instance and token.

helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana-community/grafana-mcp

For full chart options and defaults, refer to the grafana-mcp chart in the grafana-community helm-charts repository.

Next steps

Configure authentication for service accounts and tokens.
Configure transports and addresses for SSE or streamable-http in-cluster.

Client configuration examples

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

Client configuration examples

This page walks through credentials, installation options, and MCP client JSON patterns for common editors and runtimes.

The MCP server works with local Grafana and Grafana Cloud. For Grafana Cloud, use your instance URL (for example, https://myinstance.grafana.net) instead of http://localhost:3000 in the examples below.

What you’ll achieve

You can copy working configuration blocks for uvx, the binary, Docker, VS Code remote, debug mode, and TLS.

Before you begin

If you use a service account token, create a service account in Grafana with the permissions your tools need, create a token, and copy it into your config. Refer to the Grafana service account documentation.

Tip: assigning the built-in Editor role is a simple option when you do not want to tune every scope; it is broader than least-privilege.

Note
The environment variable GRAFANA_API_KEY is deprecated in favor of GRAFANA_SERVICE_ACCOUNT_TOKEN. The old name still works but may log warnings.

Install mcp-grafana using one of the methods in Set up.
Add the server block to your client configuration using one of the patterns below.

For organization targeting and custom headers, refer to Multi-organization and headers.

Multi-organization support

You can specify which organization to interact with using either:

Environment variable: Set GRAFANA_ORG_ID to the numeric organization ID
HTTP header: Set X-Grafana-Org-Id when using SSE or streamable HTTP transports (header takes precedence over environment variable - meaning you can set a default org as well).

When an organization ID is provided, the MCP server will set the X-Grafana-Org-Id header on all requests to Grafana, ensuring that operations are performed within the specified organization context.

Example with organization ID:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Custom HTTP headers

You can add arbitrary HTTP headers to all Grafana API requests using the GRAFANA_EXTRA_HEADERS environment variable. The value should be a JSON object mapping header names to values.

Example with custom headers:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

Install options

You can install mcp-grafana in several ways:

uvx (recommended): If you have uv installed, no extra setup is needed — uvx will automatically download and run the server:
Bash
```
uvx mcp-grafana
```

Docker image: Use the pre-built Docker image from Docker Hub.

Important: The Docker image’s entrypoint is configured to run the MCP server in SSE mode by default, but most users will want to use STDIO mode for direct integration with AI assistants like Claude Desktop:

STDIO Mode: For stdio mode you must explicitly override the default with -t stdio and include the -i flag to keep stdin open:

docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

SSE Mode: In this mode, the server runs as an HTTP server that clients connect to. You must expose port 8000 using the -p flag:

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana

Streamable HTTP Mode: In this mode, the server operates as an independent process that can handle multiple client connections. You must expose port 8000 using the -p flag: For this mode you must explicitly override the default with -t streamable-http

docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t streamable-http

For HTTPS streamable HTTP mode with server TLS certificates:

docker pull grafana/mcp-grafana
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 \
  --address :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Download binary: Download the latest release of mcp-grafana from the releases page and place it in your $PATH.
Build from source: If you have a Go toolchain installed you can also build and install it from source, using the GOBIN environment variable to specify the directory where the binary should be installed. This should also be in your $PATH.
Bash
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```

Deploy to Kubernetes using Helm: use the Helm chart from the grafana-community helm-charts repository

helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana-community/grafana-mcp

Add the server to your client

Add the server configuration to your client configuration file. For example, for Claude Desktop:

If using uvx:

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

If using the binary:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Note
If you see Error: spawn mcp-grafana ENOENT in Claude Desktop, specify the full path to mcp-grafana.

If using Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Note
The -t stdio argument is essential here because it overrides the default SSE mode in the Docker image.

Using VSCode with remote MCP server

If you’re using VSCode and running the MCP server in SSE mode (which is the default when using the Docker image without overriding the transport), make sure your .vscode/settings.json includes the following:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

If you terminate TLS in front of an SSE server (or the listener still speaks SSE on /sse), your client URL might look like https://localhost:8443/sse with type: "sse".

If you run streamable-http with server TLS (for example the Docker example using -t streamable-http, --address :8443, and --server.tls-*), the MCP HTTP endpoint is --endpoint-path (default /mcp), for example https://localhost:8443/mcp. That is not the same as /sse; use the client and type your editor documents for streamable HTTP, not the SSE snippet above.

Debug mode

You can enable debug mode for the Grafana transport by adding the -debug flag to the command. This will provide detailed logging of HTTP requests and responses between the MCP server and the Grafana API, which can be helpful for troubleshooting.

To use debug mode with the Claude Desktop configuration, update your config as follows:

If using the binary:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

If using Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Note
As with the standard configuration, the -t stdio argument is required to override the default SSE mode in the Docker image.

TLS configuration (client to Grafana)

If your Grafana instance is behind mTLS or requires custom TLS certificates, configure the MCP server to use the correct certificates when calling Grafana:

--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 (Go):

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)

For a shorter overview, refer to Client TLS (Grafana connection).

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: 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 \
  --address :8443

This would start the MCP server on HTTPS port 8443. Clients would then connect to https://localhost:8443/mcp instead of http://localhost:8000/mcp (the default --endpoint-path is /mcp).

Docker example: 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 \
  --address :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Refer to Server TLS (streamable-http) for more detail.