https://github.com/friendlygeorge/posthog-mcp-server
MCP server for PostHog — product analytics, events, persons, dashboards, feature flags, experiments. 13 tools.
https://github.com/friendlygeorge/posthog-mcp-server
ai-tools mcp model-context-protocol posthog product-analytics
Last synced: 8 days ago
JSON representation
MCP server for PostHog — product analytics, events, persons, dashboards, feature flags, experiments. 13 tools.
- Host: GitHub
- URL: https://github.com/friendlygeorge/posthog-mcp-server
- Owner: friendlygeorge
- License: mit
- Created: 2026-06-06T05:00:20.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-06-06T06:55:44.000Z (15 days ago)
- Last Synced: 2026-06-06T08:20:29.109Z (15 days ago)
- Topics: ai-tools, mcp, model-context-protocol, posthog, product-analytics
- Language: JavaScript
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PostHog MCP Server
> Connect AI assistants to [PostHog](https://posthog.com/) — 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`:
```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`):
```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)
```bash
# 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
```bash
npm install
npm run dev # Build and run
npm run build # Build only
npm start # Run built output
```
## License
MIT © Nova