PostHog Context Capture

CLI and MCP server to look up PostHog persons and their events for debugging.

Installation

npm install -g posthog-context-capture

Setup

Set environment variables:

export POSTHOG_PERSONAL_API_KEY=phx_...
export POSTHOG_PROJECT_ID=12345
export POSTHOG_REGION=us  # or "eu"

Getting Your Credentials

Personal API Key:

1. Go to Settings → Personal API keys in PostHog
2. Click "+ Create a personal API Key"
3. Select the query:read scope
4. Copy the key (starts with phx_)

Project ID: Found in your PostHog URL: https://us.posthog.com/project/12345/...

CLI Usage

# Look up person by email
posthog-lookup --email [email protected]

# With recent events (defaults to last 30 days)
posthog-lookup --email [email protected] --events 100

# Filter by timeframe
posthog-lookup --email [email protected] --from 7d
posthog-lookup --email [email protected] --from 2024-01-01 --to 2024-01-31

# Filter by event type
posthog-lookup --email [email protected] --event-type pageview

# Find persons by event
posthog-lookup --event checkout_failed --limit 10
posthog-lookup --event subscription_cancelled --from 7d --show-properties

MCP Server

The MCP server exposes PostHog lookup tools to AI assistants.

Claude Code

Global (all projects) — add to ~/.mcp.json:

{
  "mcpServers": {
    "posthog": {
      "type": "stdio",
      "command": "posthog-mcp",
      "env": {
        "POSTHOG_PERSONAL_API_KEY": "phx_...",
        "POSTHOG_PROJECT_ID": "12345",
        "POSTHOG_REGION": "us"
      }
    }
  }
}

Per-project — add .mcp.json to your project root with the same config.

Restart Claude Code after adding. You'll be prompted to approve the server on first use.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "posthog": {
      "command": "posthog-mcp",
      "env": {
        "POSTHOG_PERSONAL_API_KEY": "phx_...",
        "POSTHOG_PROJECT_ID": "12345",
        "POSTHOG_REGION": "us"
      }
    }
  }
}

Cursor

Add to Cursor settings (Cursor Settings → MCP), or create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "posthog": {
      "command": "posthog-mcp",
      "env": {
        "POSTHOG_PERSONAL_API_KEY": "phx_...",
        "POSTHOG_PROJECT_ID": "12345",
        "POSTHOG_REGION": "us"
      }
    }
  }
}

Available Tools

• lookup_person_by_email - Find a person by email with their recent events
• lookup_persons_by_event - Find persons who triggered a specific event
• get_person_events - Get events for a specific person ID

License

MIT