This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Developer resourcesbreadcrumb arrow Grafana MCP serverbreadcrumb arrow Clientsbreadcrumb arrow Claude Code
Enterprise Open source

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

Bash 
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.

Bash 
# 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:

ScopeDescription
local (default)Available only to you in current project
projectShared with team via .mcp.json file
userAvailable to you across all projects
Bash 
# 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

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

Docker setup

Bash 
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

Bash 
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:

Bash 
claude --debug

Verify configuration

  1. Start a new Claude Code session:

    Bash 
    claude

  2. Ask: “List my Grafana dashboards”

  3. Claude should use the Grafana MCP tools automatically

View current configuration

Bash 
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

Bash 
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