: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.
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:
- Resolve the right Tailscale hostname for the selected region
- Pull the service account token from macOS Keychain
- 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, orgrafana-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:
- Go to Administration > Service accounts
- Create a new service account (or use an existing one)
- Add a token with appropriate permissions (typically Viewer or Editor)
- 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):
GRAFANA_REGIONenv var — set in your MCP client config (recommended for multi-server setups)~/.grafana-regionfile — set via thegrafana-regioncommand- Default —
usif 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
/exitto 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:
- Pins
GRAFANA_REGION=uson your existinggrafanaentry - Adds a
grafana-euentry (clone ofgrafanawithGRAFANA_REGION=eu) - Duplicates your
mcp__grafana__*permissions formcp__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.