Set up by client on Grafana Labs

Claude Desktop

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

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: Go install

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

Option 2: Download binary

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

Option 3: 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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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

Thu, 23 Apr 2026 10:03:11 +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.