Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

10.4 KB
Raw Blame

MCP Server Scripts

Scripts for connecting AI assistants (Claude Code, Cursor, etc.) to PostHog's internal Grafana instances via the Grafana MCP server.

Why these scripts exist

PostHog's Grafana instances are reachable directly over Tailscale at plain HTTP hostnames (grafana-prod-us, grafana-prod-eu, grafana-dev, grafana-internal, grafana-mw-dev, grafana-mw-prod-us, grafana-mw-prod-eu, grafana-infra-dev, grafana-infra-dev-wl). Authentication is handled at the Grafana layer via a service account Bearer token, which the Grafana MCP server supports natively.

These scripts glue that together:

  1. Resolve the right Tailscale hostname for the selected region
  2. Pull the service account token from macOS Keychain
  3. Hand both to mcp-grafana

Connecting without the wrapper

The wrapper is optional. mcp-grafana accepts the Grafana URL and service account token directly. Tailscale provides network access; Grafana still requires authentication. You still need an MCP server process to translate tool calls into Grafana API requests.

To connect to internal without the wrapper, configure your MCP client:

{
  "mcpServers": {
    "grafana-internal": {
      "command": "/Users/YOUR_USERNAME/go/bin/mcp-grafana",
      "args": ["-disable-write"],
      "env": {
        "GRAFANA_URL": "http://grafana-internal"
      }
    }
  }
}

Adjust the binary path to match your installation. Supply GRAFANA_SERVICE_ACCOUNT_TOKEN through your client's secret configuration or inherited environment. Do not commit tokens to MCP configuration files. Use a Viewer service account for read-only access.

Keep the wrapper if you want per-environment tokens in macOS Keychain or the grafana-region switcher. The wrapper does not add a proxy, tunnel, or authentication bypass.

Prerequisites

  • Tailscale connected, with access to the selected Grafana host (grafana-prod-us, grafana-prod-eu, grafana-dev, grafana-internal, grafana-mw-dev, grafana-mw-prod-us, grafana-mw-prod-eu, grafana-infra-dev, or grafana-infra-dev-wl)
  • mcp-grafana binary installed
  • macOS (for Keychain-based token storage) or Linux with environment variables

Installing mcp-grafana

go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Make sure $GOPATH/bin (usually ~/go/bin) is in your PATH.

Setup

1. Create Grafana service account tokens

For each region you need access to, create a service account token in Grafana:

  1. Go to Administration > Service accounts
  2. Create a new service account (or use an existing one)
  3. Add a token with appropriate permissions (typically Viewer or Editor)
  4. Copy the token

2. Add scripts to your PATH

Add the following to your shell config file (~/.zshrc, ~/.bashrc, or equivalent):

# PostHog infra scripts (grafana-region, grafana-token, etc.)
export PATH="$HOME/dev/posthog/posthog/tools/infra-scripts/mcp:$PATH"

Adjust the path if your PostHog repo is in a different location. Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

3. Store tokens in Keychain (macOS)

grafana-token us <your-us-token>
grafana-token eu <your-eu-token>
grafana-token dev <your-dev-token>  # optional
grafana-token internal <your-internal-token>  # optional
grafana-token mw-dev <your-mw-dev-token>  # optional
grafana-token mw-prod-us <your-mw-prod-us-token>  # optional
grafana-token mw-prod-eu <your-mw-prod-eu-token>  # optional
grafana-token infra-dev <your-infra-dev-token>  # optional
grafana-token infra-dev-wl <your-infra-dev-wl-token>  # optional

4. Configure your MCP client

Add the wrapper script to your MCP client configuration. See the Usage section for single-server and multi-server configuration examples.

For a basic single-server setup, add to your MCP settings (~/.config/claude-code/.mcp.json for Claude Code, or your editor's MCP config):

{
  "mcpServers": {
    "grafana": {
      "command": "/Users/YOUR_USERNAME/dev/posthog/posthog/tools/infra-scripts/mcp/mcp-grafana-wrapper.sh",
      "args": []
    }
  }
}

Usage

Region selection

The wrapper script determines which Grafana region to connect to using (in order of precedence):

  1. GRAFANA_REGION env var — set in your MCP client config (recommended for multi-server setups)
  2. ~/.grafana-region file — set via the grafana-region command
  3. Default — us if neither is set

Region → host mapping:

Region Tailscale host
us http://grafana-prod-us
eu http://grafana-prod-eu
dev http://grafana-dev
internal http://grafana-internal
mw-dev http://grafana-mw-dev
mw-prod-us http://grafana-mw-prod-us
mw-prod-eu http://grafana-mw-prod-eu
infra-dev http://grafana-infra-dev
infra-dev-wl http://grafana-infra-dev-wl

Single-server setup (switching regions manually)

Use the grafana-region command to switch between PostHog environments:

grafana-region          # Show current region
grafana-region us       # Switch to prod-us (us-east-1)
grafana-region eu       # Switch to prod-eu (eu-central-1)
grafana-region dev      # Switch to dev environment
grafana-region internal # Switch to internal environment
grafana-region mw-dev   # Switch to mw-dev (same for mw-prod-us, mw-prod-eu, infra-dev, infra-dev-wl)

Important: Restart required after switching regions

MCP servers are initialized once when your AI assistant starts. The region is read at startup, so changing the region while the assistant is running has no effect until you restart.

To restart and apply the new region:

  • Claude Code: Type /exit to quit, then restart Claude Code
  • Cursor: Close and reopen the editor, or restart the MCP server from settings
  • VS Code: Reload the window (Cmd+Shift+P → "Developer: Reload Window")

Multi-server setup (both regions simultaneously)

Run two MCP server instances with the GRAFANA_REGION env var so both regions are available without restarting. You can also use -disable-* flags to reduce the tool surface per server (see mcp-grafana --help for the full list).

Claude Code

Add to ~/.config/claude-code/.mcp.json:

{
  "mcpServers": {
    "grafana": {
      "command": "/Users/YOUR_USERNAME/dev/posthog/posthog/tools/infra-scripts/mcp/mcp-grafana-wrapper.sh",
      "args": ["-disable-admin", "-disable-alerting", "-disable-incident", "-disable-oncall"],
      "env": { "GRAFANA_REGION": "us" }
    },
    "grafana-eu": {
      "command": "/Users/YOUR_USERNAME/dev/posthog/posthog/tools/infra-scripts/mcp/mcp-grafana-wrapper.sh",
      "args": ["-disable-admin", "-disable-alerting", "-disable-incident", "-disable-oncall"],
      "env": { "GRAFANA_REGION": "eu" }
    }
  }
}

To add internal alongside those servers, add a grafana-internal entry to mcpServers:

{
  "command": "/Users/YOUR_USERNAME/dev/posthog/posthog/tools/infra-scripts/mcp/mcp-grafana-wrapper.sh",
  "args": ["-disable-write"],
  "env": { "GRAFANA_REGION": "internal" }
}

Store its token with grafana-token internal <your-internal-token>, then restart your MCP client. The mw-dev, mw-prod-us, mw-prod-eu, infra-dev, and infra-dev-wl regions work the same way: set GRAFANA_REGION to the region and store its token with grafana-token <region> <token>. Supported regions are explicit so each selection maps to a known host and its own Keychain token.

Migrating from single-server to multi-server

If you already have a single grafana server configured with both US and EU tokens in Keychain, run the migration script:

grafana-migrate-multi            # migrate with confirmation prompt
grafana-migrate-multi --dry-run  # preview changes without writing
grafana-migrate-multi --slim     # also normalize to recommended (smaller) disable-flag set

The script:

  1. Pins GRAFANA_REGION=us on your existing grafana entry
  2. Adds a grafana-eu entry (clone of grafana with GRAFANA_REGION=eu)
  3. Duplicates your mcp__grafana__* permissions for mcp__grafana-eu__* in ~/.claude/settings.json

With --slim, it also replaces the args on both entries with the recommended set (-disable-admin, -disable-alerting, -disable-incident, -disable-oncall), removing any extra disable flags you may have accumulated.

Backups of modified files are saved with a .bak extension. After migrating, restart your MCP client. The grafana-region command is no longer needed since each server has its region pinned via env var.

Checking token status

grafana-token           # Show status of all tokens
grafana-token us        # Check if US token is configured

Linux support

On Linux, Keychain is not available. Instead, set the GRAFANA_SERVICE_ACCOUNT_TOKEN environment variable before starting your MCP client:

export GRAFANA_SERVICE_ACCOUNT_TOKEN="your-token-here"

You may want to use a secrets manager or encrypted file for production use.

Troubleshooting

Hostname doesn't resolve / connection refused

The Tailscale hostnames (grafana-prod-us, grafana-prod-eu, grafana-dev, grafana-internal, grafana-mw-*, grafana-infra-dev*) only resolve when Tailscale is connected to the PostHog tailnet. Check with:

tailscale status

If you're not connected, run tailscale up (or open the Tailscale app) and ensure you're logged into the PostHog tailnet.

"mcp-grafana not found"

Install it with:

go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Or set MCP_GRAFANA_BIN to the full path of the binary.

"Could not retrieve token from keychain"

Store your token first:

grafana-token us <your-token>

401 Unauthorized from Grafana

Your service account token may have been revoked or expired. Create a new one in Grafana (Administration > Service accounts) and store it:

grafana-token us <new-token>

Then restart your MCP client.

Available Grafana MCP tools

Once connected, you'll have access to Grafana MCP tools including:

  • Dashboard search and retrieval
  • Prometheus/Loki querying
  • Alert rule listing
  • Incident management
  • On-call schedule viewing

See the mcp-grafana documentation for the full list of available tools.