Claude Desktop

This guide helps you set up the mcp-grafana server for Claude Desktop.

Prerequisites

Claude Desktop installed
Grafana 9.0+ with a service account token
mcp-grafana binary in your PATH

Installation

Option 1: Desktop extension (.mcpb)

Download mcp-grafana_<version>.mcpb from GitHub Releases and open it with Claude Desktop. The bundle carries the server binary for every supported platform, and Claude Desktop prompts you for your Grafana URL and credentials, so you do not need to edit any configuration file. Skip the rest of this page if you install this way.

Bundles are not code-signed, and the copy listed in Claude Desktop’s extension directory may lag behind the latest release.

Option 2: Go install

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

Option 3: Download binary

Get the latest release from GitHub Releases and add to your PATH.

Option 4: Docker

No installation needed – use Docker in the configuration below.

Configuration

Edit your Claude Desktop configuration file:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Binary configuration

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

If you get ENOENT, use the full path:

{
  "mcpServers": {
    "grafana": {
      "command": "/Users/yourname/go/bin/mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}

Docker configuration

{
  "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://host.docker.internal:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your-token>"
      }
    }
  }
}

Debug mode

Add -debug to args for verbose logging:

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

Verify configuration

Fully quit Claude Desktop (Cmd+Q on macOS)
Restart Claude Desktop
Open a new conversation
Ask: “List my Grafana dashboards”

If it works, you’ll see dashboard names. If not, check logs at ~/Library/Logs/Claude/mcp*.log (macOS).

Read-only mode

Prevent accidental modifications:

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

TLS client certificates

For Grafana instances requiring mTLS:

{
  "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-token>"
      }
    }
  }
}