io.github.friendlygeorge/posthog-mcp-server

PostHog MCP Server

Connect AI assistants to PostHog — query events, persons, insights, dashboards, feature flags, cohorts, and experiments through the Model Context Protocol.

Works with Claude Desktop, Cursor, Windsurf, Cline, Continue, and any MCP-compatible client.

Features

Tool	Description
list_events	Query events with filters (event name, person, date range, properties)
get_person	Get a person (user) by distinct_id — properties, creation date, event count
list_persons	Search and list persons with pagination
list_dashboards	List all dashboards — names, tags, widget counts
get_dashboard	Get a specific dashboard with its insights and widgets
execute_insight	Execute a saved insight (trend, funnel, etc.) and get results
list_feature_flags	List all feature flags — key, active status, rollout percentage
evaluate_feature_flag	Evaluate a flag for a specific user and get variant value
list_cohorts	List cohorts — name, type (dynamic/static/SQL), person count
list_experiments	List A/B tests — name, status, feature flag, dates
get_experiment	Get experiment results with variant data and statistical significance
list_actions	List custom event actions/definitions
get_project_info	Get project name, ID, settings, and data region

Quick Start

1. Get a PostHog API Key

Go to PostHog → Settings → Personal API Keys and create a key with read access.

Or visit: https://your-instance.posthog.com/settings/user-api-keys

2. Configure your MCP client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "posthog-mcp-server"],
      "env": {
        "POSTHOG_API_KEY": "phx_YOUR_API_KEY_HERE",
        "POSTHOG_HOST": "https://us.i.posthog.com",
        "POSTHOG_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Cursor — add to MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "posthog-mcp-server"],
      "env": {
        "POSTHOG_API_KEY": "phx_YOUR_API_KEY_HERE",
        "POSTHOG_HOST": "https://us.i.posthog.com",
        "POSTHOG_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

3. Run manually (for testing)

# Clone and build
git clone https://github.com/friendlygeorge/posthog-mcp-server.git
cd posthog-mcp-server
npm install
npm run build

# Run
POSTHOG_API_KEY=phx_... POSTHOG_PROJECT=12345 node dist/index.js

Environment Variables

Variable	Required	Default	Description
POSTHOG_API_KEY	✅	—	Your PostHog personal API key (phx_...)
POSTHOG_HOST	❌	https://us.i.posthog.com	PostHog instance URL (use https://eu.i.posthog.com for EU)
POSTHOG_PROJECT	❌	""	Default project ID. If empty, must be specified per-call.

Self-hosted PostHog

If you run PostHog on your own infrastructure, set POSTHOG_HOST to your instance URL:

POSTHOG_HOST=https://posthog.yourcompany.com

Example Queries

Once configured, ask your AI assistant:

• "Show me the last 20 pageview events"
• "Who are the most active users this week?"
• "What's the status of our signup conversion experiment?"
• "Is the new-checkout-flow feature flag enabled for user abc123?"
• "Show me all active dashboards"
• "Execute insight 42 and show me the trend"
• "List all feature flags that are currently active"
• "How many people are in the 'Power Users' cohort?"

API Reference

This server wraps the PostHog REST API (v1). Full documentation:

• PostHog API docs: https://posthog.com/docs/api
• MCP protocol: https://modelcontextprotocol.io
• PostHog: https://posthog.com

Development

npm install
npm run dev     # Build and run
npm run build   # Build only
npm start       # Run built output

License

MIT © Nova