posthog-mcp

An MCP (Model Context Protocol) server that wraps the PostHog REST API, letting AI agents query your analytics data directly via tool calls — no browser tab required.

Works with Claude Desktop, Cursor, and any other MCP-compatible client.

What it does

Exposes five tools that cover the most common PostHog workflows:

Related MCP server: Posthog Universal MCP Server

Prerequisites

• Node.js 18+

• A PostHog account with a personal API key (Settings → Personal API Keys)

• Your project ID (visible in Project Settings or in the URL: /project/<id>/)

Installation

git clone https://github.com/johnnikolo/posthog-mcp.git
cd posthog-mcp
npm install
npm run build

Configuration

The server is configured via environment variables:

Wiring it up in Claude Desktop

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

{
  "mcpServers": {
    "posthog": {
      "command": "node",
      "args": ["/absolute/path/to/posthog-mcp/dist/index.js"],
      "env": {
        "POSTHOG_API_KEY": "phx_your_key_here",
        "POSTHOG_PROJECT_ID": "12345"
      }
    }
  }
}

Restart Claude Desktop and the PostHog tools will appear automatically.

Tools reference

get_insights

Retrieve a saved PostHog insight by its numeric ID.

What does insight 42 show?
→ calls get_insights({ insight_id: 42 })

Parameters

• insight_id (number, required) — the insight's ID

• refresh (boolean, default false) — force a fresh calculation

list_events

Fetch recent events with optional filters.

Show me the last 50 user_signed_up events from the past week
→ calls list_events({ event: "user_signed_up", after: "2024-01-01T00:00:00Z", limit: 50 })

Parameters

• event (string) — filter to a specific event name

• after / before (ISO 8601 string) — date range

• limit (number, default 100, max 500)

• distinct_id (string) — filter to a single user

get_feature_flags

List all feature flags with their rollout configuration.

Which feature flags are currently active?
→ calls get_feature_flags({ active_only: true })

Parameters

• active_only (boolean, default false) — return only enabled flags

query_trends

Run a trends query and get back a time series.

How many $pageview and user_signed_up events happened per day over the last 30 days?
→ calls query_trends({ events: ["$pageview", "user_signed_up"], date_from: "-30d", interval: "day" })

Parameters

• events (string[], required) — event names to include

• date_from (string, default "-7d") — start of range (relative or ISO 8601)

• date_to (string) — end of range (defaults to now)

• interval ("hour" | "day" | "week" | "month", default "day")

• breakdown (string) — property to break results down by (e.g. "$browser")

get_persons

Look up person profiles.

Find the user with distinct ID "user_abc123"
→ calls get_persons({ distinct_id: "user_abc123" })

Parameters

• distinct_id (string) — look up a specific person

• search (string) — search by email, name, or property

• limit (number, default 20, max 100)

Development

# run directly without building
npm run dev

# type-check only
npm run typecheck

License

MIT