Set up by client on Grafana Labs

Claude Desktop

Fri, 21 Aug 2026 10:19:21 +0000

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

Next steps

Set up for other install options (uvx, Helm).
Configure authentication for Grafana credentials.

Cursor

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

Cursor

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

Prerequisites

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

Configuration

Two options for configuration location:

Scope	Path
Global (all projects)	`~/.cursor/mcp.json`
Project-specific	`.cursor/mcp.json` in project root

Add using the UI

Open Cursor Settings -> Tools & Integrations
Click New MCP Server
This opens ~/.cursor/mcp.json for editing

Manual configuration

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "grafana": {
      "command": "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

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

Verify configuration

Go to Cursor Settings -> Tools & Integrations
Find grafana in the MCP servers list
Click the refresh button if needed
Green indicator = server running
Open Composer and ask: “List my Grafana dashboards”

Troubleshooting

Server not appearing:

Check JSON syntax (trailing commas break it)
Restart Cursor
Verify binary path: which mcp-grafana

Tools not working:

Click refresh button in MCP settings
Check Grafana token permissions
Enable -debug flag and check output

Read-only mode

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

Next steps

Set up for other install options (uvx, Helm).
Configure authentication for Grafana credentials.

Codex CLI

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

Codex CLI

This guide helps you set up the mcp-grafana server for the OpenAI Codex CLI.

Prerequisites

Codex CLI installed (npm install -g @openai/codex)
Grafana 9.0+ with a service account token
mcp-grafana binary in your PATH

Important: TOML format

Codex uses TOML configuration, not JSON. Configuration file: ~/.codex/config.toml

Configuration

CLI setup (recommended)

codex mcp add grafana -- mcp-grafana

Add environment variables:

codex mcp add grafana \
  --env GRAFANA_URL=http://localhost:3000 \
  --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token> \
  -- mcp-grafana

Manual configuration

Create or edit ~/.codex/config.toml:

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

Note: Use mcp_servers (underscore, not hyphen).

Debug mode

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

Docker setup

[mcp_servers.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>" }

Verify configuration

# List configured servers
codex mcp list

# Show specific server config
codex mcp get grafana

# Start Codex and test
codex

Then ask: “List my Grafana dashboards”

Timeout settings

If Grafana operations take time, increase timeout:

[mcp_servers.grafana]
command = "mcp-grafana"
args = []
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
startup_timeout_ms = 20000
tool_timeout_ms = 120000

Troubleshooting

Server not found in Codex:

Verify TOML syntax (no trailing commas, use = not :)
Check key is mcp_servers not mcp-servers
Restart Codex after configuration changes

Config shared across CLI and IDE: Codex CLI and VS Code extension share ~/.codex/config.toml. A syntax error breaks both.

Common TOML mistakes:

# Wrong - JSON-style
env = {"GRAFANA_URL": "http://localhost:3000"}

# Correct - TOML-style
env = { GRAFANA_URL = "http://localhost:3000" }

Read-only mode

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

Next steps

Set up for other install options.
Configure authentication for Grafana credentials.

VS Code and GitHub Copilot

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

VS Code and GitHub Copilot

This guide helps you set up the mcp-grafana server for VS Code with GitHub Copilot agent mode.

Prerequisites

VS Code with GitHub Copilot extension
Grafana 9.0+ with a service account token
mcp-grafana binary installed

Important

GitHub Copilot in VS Code uses SSE transport, not stdio. You need to run mcp-grafana as an HTTP server.

Setup

1. Start the MCP server

export GRAFANA_URL="http://localhost:3000"
export GRAFANA_SERVICE_ACCOUNT_TOKEN="<your-token>"
mcp-grafana --transport sse --address localhost:8000

Or with Docker:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://host.docker.internal:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token> \
  grafana/mcp-grafana --transport sse --address :8000

2. Configure VS Code

Add to your VS Code settings (settings.json):

{
  "github.copilot.chat.mcpServers": {
    "grafana": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Or use workspace settings (.vscode/settings.json) for project-specific config.

Debug mode

Start the server with debug logging:

mcp-grafana --transport sse --address localhost:8000 -debug

Verify configuration

Restart VS Code after configuration changes
Open Copilot Chat (Ctrl+Shift+I)
Type: @grafana list dashboards
If tools are available, Copilot will query Grafana

Troubleshooting

Server not connecting:

Verify server is running: curl http://localhost:8000/sse
Check firewall allows port 8000
Restart VS Code after configuration changes

Tools not appearing:

GitHub Copilot agent mode required (may need Copilot Chat enabled)
Check VS Code output panel for MCP errors

Running as a service

For persistent server, create a systemd unit or launchd plist.

Linux systemd (~/.config/systemd/user/mcp-grafana.service):

[Unit]
Description=Grafana MCP Server
After=network.target

[Service]
ExecStart=/path/to/mcp-grafana --transport sse --address localhost:8000
Environment=GRAFANA_URL=http://localhost:3000
Environment=GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token>
Restart=always

[Install]
WantedBy=default.target

Enable with:

systemctl --user enable --now mcp-grafana

Read-only mode

mcp-grafana --transport sse --address localhost:8000 --disable-write

Next steps

Transports and addresses for SSE details.
Configure authentication for Grafana credentials.

Claude Code

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

Claude Code

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

Prerequisites

Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
Grafana 9.0+ with a service account token
mcp-grafana binary in your PATH

One-command setup

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

Manual configuration

Claude Code stores MCP configuration alongside other settings. Use the CLI to manage servers.

# List configured servers
claude mcp list

# Add a server
claude mcp add grafana -- mcp-grafana

# Remove a server
claude mcp remove grafana

Scope options

Claude Code supports three scopes for MCP servers:

Scope	Description
`local` (default)	Available only to you in current project
`project`	Shared with team via `.mcp.json` file
`user`	Available to you across all projects

# Add for all your projects
claude mcp add grafana --scope user -- mcp-grafana

# Add for current project only (default)
claude mcp add grafana --scope local -- mcp-grafana

Full configuration with environment variables

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

Docker setup

claude mcp add-json "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

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

Then run Claude Code with debug output:

claude --debug

Verify configuration

Start a new Claude Code session:
Bash
```
claude
```
Ask: “List my Grafana dashboards”
Claude should use the Grafana MCP tools automatically

View current configuration

claude mcp list --json

Troubleshooting

Server not found:

Verify binary path: which mcp-grafana
Use full path in configuration if needed

Permission errors:

Check Grafana service account token
Verify token has required RBAC permissions

Read-only mode

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

Next steps

Set up for other install options.
Configure authentication for Grafana credentials.

Gemini CLI

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

Gemini CLI

This guide helps you set up the mcp-grafana server for the Google Gemini CLI.

Prerequisites

Gemini CLI installed (npm install -g @google/gemini-cli)
Grafana 9.0+ with a service account token
mcp-grafana binary in your PATH

Configuration

Gemini CLI stores MCP configuration in ~/.gemini/settings.json.

Manual configuration

Create or edit ~/.gemini/settings.json:

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

CLI commands

# List configured servers
gemini mcp list

# Remove a server
gemini mcp remove grafana

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

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

Verify configuration

Start Gemini CLI:
Bash
```
gemini
```
Run /mcp to see available tools
Ask: “List my Grafana dashboards”

SSE transport (remote server)

For HTTP-based connection:

Start mcp-grafana as an HTTP server:

export GRAFANA_URL="http://localhost:3000"
export GRAFANA_SERVICE_ACCOUNT_TOKEN="<your-token>"
mcp-grafana --transport sse --address localhost:8000

Configure in settings.json:

{
  "mcpServers": {
    "grafana": {
      "httpUrl": "http://localhost:8000/sse"
    }
  }
}

Troubleshooting

Tools not appearing:

Run /mcp in Gemini CLI to check registered tools
Verify settings.json syntax
Check binary path: which mcp-grafana

Connection errors:

Verify GRAFANA_URL is reachable
Check token permissions in Grafana

Read-only mode

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

Next steps

Set up for other install options.
Configure authentication for Grafana credentials.

Windsurf

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

Windsurf

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

Prerequisites

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

Configuration

Configuration file location:

OS	Path
macOS/Linux	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

Add using the UI

Open Windsurf Settings (Cmd+Shift+P -> Open Windsurf Settings)
Scroll to Cascade section
Click Add Server or View raw config

Manual configuration

Create or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "grafana": {
      "command": "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

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

Verify configuration

Click the refresh button after adding the server
Open Cascade view
Click the hammer icon (MCP servers)
Grafana should show green status
Ask: “List my Grafana dashboards”

Tool limit

Windsurf limits total MCP tools to 100. If you hit the limit:

Go to Windsurf Settings -> Manage plugins
Disable unused servers
Toggle off individual tools you don’t need

Troubleshooting

Server not connecting:

Press refresh button in Cascade settings
Check JSON syntax
Verify binary exists: which mcp-grafana

SSE transport (remote server):

If you need HTTP-based connection instead of stdio:

mcp-grafana --transport streamable-http --address localhost:8000

Then configure with serverUrl:

{
  "mcpServers": {
    "grafana": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}

Read-only mode

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

Next steps

Set up for other install options.
Configure authentication for Grafana credentials.

Zed

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

Zed

This guide helps you set up the mcp-grafana server for the Zed editor.

Prerequisites

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

Configuration

Zed uses context_servers in settings.json, not mcpServers.

Add using the UI

Open Agent Panel (Cmd+Shift+A)
Click Settings (gear icon)
Click Add Custom Server
Fill in command and args

Manual configuration

Open Zed settings (Cmd+,) and add:

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

Note: Zed uses context_servers, not mcpServers.

Docker configuration

{
  "context_servers": {
    "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

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

Verify configuration

Open Agent Panel settings
Check indicator next to grafana
- Green = server active
- Other colors = check tooltip for status
Open Agent Panel chat
Ask: “List my Grafana dashboards”

Tip: Mention “grafana” in your prompt to help the model pick the right tools.

Tool permissions

By default, Zed asks permission for each tool call. To auto-allow:

{
  "agent": {
    "always_allow_tool_actions": true
  }
}

Use with caution – this enables all MCP tools without confirmation.

Troubleshooting

Server not starting:

Check Zed logs: Cmd+Shift+P -> zed: open logs
Verify binary path: which mcp-grafana
Restart Zed after configuration changes

Tools not appearing:

Zed supports both stdio and HTTP transports
For remote servers, use native URL syntax or mcp-remote shim

Remote server (native URL syntax):

Zed supports direct URL connections for remote MCP servers:

{
  "context_servers": {
    "grafana": {
      "url": "http://localhost:8000/sse",
      "headers": {}
    }
  }
}

First start the server:

mcp-grafana --transport sse --address localhost:8000

Remote server (mcp-remote fallback):

Alternative using mcp-remote shim:

{
  "context_servers": {
    "grafana": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/sse"]
    }
  }
}

Read-only mode

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

Next steps

Set up for other install options.
Configure authentication for Grafana credentials.