tools/infra-scripts/mcp/README.md
Scripts for connecting AI assistants (Claude Code, Cursor, etc.) to PostHog's internal Grafana instances via the Grafana MCP server.
PostHog's Grafana instances are protected by Cognito OAuth at the AWS ALB level. This authentication method doesn't support Bearer token authentication, which the Grafana MCP server requires. These scripts work around this by:
aws sso login)go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
Make sure $GOPATH/bin (usually ~/go/bin) is in your PATH.
For each region you need access to, create a service account token in Grafana:
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
grafana-token us <your-us-token>
grafana-token eu <your-eu-token>
grafana-token dev <your-dev-token> # optional
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": []
}
}
}
The wrapper script determines which Grafana region to connect to using (in order of precedence):
GRAFANA_REGION env var — set in your MCP client config (recommended for multi-server setups)~/.grafana-region file — set via the grafana-region commandus if neither is setUse 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
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:
/exit to quit, then restart Claude CodeCmd+Shift+P → "Developer: Reload Window")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).
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" }
}
}
}
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:
GRAFANA_REGION=us on your existing grafana entrygrafana-eu entry (clone of grafana with GRAFANA_REGION=eu)mcp__grafana__* permissions for mcp__grafana-eu__* in ~/.claude/settings.jsonWith --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.
grafana-token # Show status of all tokens
grafana-token us # Check if US token is configured
The wrapper script automatically manages kubectl port-forwards:
Port-forwards persist between MCP client restarts. If you need to restart them:
# Find and kill existing port-forwards
pkill -f "kubectl.*port-forward.*grafana"
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.
Your AWS SSO session may have expired:
aws sso login
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.
Store your token first:
grafana-token us <your-token>
Check if there's a stale port-forward process:
# Check for existing port-forwards
ps aux | grep "kubectl.*port-forward.*grafana"
# Kill stale processes
pkill -f "kubectl.*port-forward.*grafana"
# Remove stale PID files
rm -f ~/.local/run/grafana-port-forward-*.pid
Once connected, you'll have access to Grafana MCP tools including:
See the mcp-grafana documentation for the full list of available tools.