PostHog MCP Server

PostHog MCP

The official MCP server for PostHog. PostHog makes your product self-driving — it reads your data and ships changes with you, never without you — and this server gives MCP clients (Claude, Cursor, VS Code, Zed, and more) that full surface: analytics and SQL, dashboards, experiments, feature flags, surveys, session replay, error tracking, and more.

Documentation: https://posthog.com/docs/model-context-protocol

Use the MCP Server

Quick install

You can install the MCP server automatically into Cursor, Claude, Claude Code, VS Code and Zed by running the following command:

npx @posthog/wizard@latest mcp add

Manual install

1. Obtain a personal API key using the MCP Server preset.

1. Add the MCP configuration to your desktop client (e.g. Cursor, Windsurf, Claude Desktop) and add your personal API key

{

"mcpServers": { "posthog": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.posthog.com/mcp", "--header", "Authorization:${POSTHOG_AUTH_HEADER}" ], "env": { "POSTHOG_AUTH_HEADER": "Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}" } } } }

Minimal Node client (Streamable HTTP)

If you want to call MCP from Node (outside an IDE), use the Model Context Protocol SDK’s Streamable HTTP transport.

• Auth: Use a personal PostHog API key and pass it as a Bearer token in Authorization.
• Accept header: Clients must include Accept: application/json, text/event-stream.
• Lifecycle: MCP requires initialize then a client notifications/initialized; the SDK performs this during connect().

// tools-list.mjs

import { Client } from '@modelcontextprotocol/sdk/client/index.js' import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js' import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js' import { mkdirSync, writeFileSync } from 'node:fs' import { join } from 'node:path' import { URL } from 'node:url'

const AUTH = process.env.POSTHOG_AUTH_HEADER // "Bearer phx_…" const MCP_URL = process.env.MCP_URL || 'https://mcp.posthog.com/mcp'

if (!AUTH?.startsWith('Bearer ')) { console.error('Set POSTHOG_AUTH_HEADER="Bearer phx_..."') process.exit(1) }

const transport = new StreamableHTTPClientTransport(new URL(MCP_URL), { requestInit: { headers: { Authorization: AUTH, // Required for Streamable HTTP (JSON + SSE) Accept: 'application/json, text/event-stream', }, }, serverInfo: { name: 'example-node-client', version: '0.0.1' }, })

const client = new Client({ name: 'example-node-client', version: '0.0.1' })

// Handles initialize + notifications/initialized await client.connect(transport)

const toolsResp = await client.request({ method: 'tools/list' }, ListToolsResultSchema) // { tools: [...] } const tools = toolsResp?.tools ?? [] console.log('Tools:', tools.length)

// (Optional) Save the full JSON-RPC envelope to a file (run from repo root) const envelope = { jsonrpc: '2.0', id: 'list-1', result: toolsResp } mkdirSync('reports', { recursive: true }) writeFileSync(join('reports', 'tools-list-http.json'), JSON.stringify(envelope, null, 2)) console.log('Saved: reports/tools-list-http.json')

await client.close()

Why these headers & steps?

• Streamable HTTP requires the Accept header to include both JSON and SSE.
• After initialize, the client must send notifications/initialized; the SDK does this for you in connect().

See also the main PostHog MCP docs for available tools and setup flows: https://posthog.com/docs/model-context-protocol

Example Prompts

Below are detailed examples showing realistic prompts and expected outputs:

Example 1: Feature flag management

Prompt: "Create a feature flag called 'new-checkout-flow' that's enabled for 20% of users, and show me the configuration"

What happens:

1. The create-feature-flag tool creates the flag with a 20% rollout
2. Returns the flag configuration including the key, rollout percentage, and targeting rules

Expected output:

Created feature flag 'new-checkout-flow':

• Key: new-checkout-flow
• Active: true
• Rollout: 20% of all users
• URL: https://us.posthog.com/project/ /feature_flags/12345

Example 2: Analytics query

Prompt: "How many unique users signed up in the last 7 days, broken down by day?"

What happens:

1. The query-trends tool executes a trends query filtering for $signup events
2. Returns daily counts with unique user aggregation

Expected output:

Signups over the last 7 days:

Total: 847 unique signups

Example 3: A/B test creation and monitoring

Prompt: "Create an A/B test for our pricing page that measures conversion to the checkout page"

What happens:

1. The experiment-create tool creates an experiment with control/test variants
2. Sets up a funnel metric: pricing page view → checkout page view
3. Creates an associated feature flag for variant assignment

Expected output:

Created experiment 'Pricing page test':

• Feature flag: pricing-page-test
• Variants: control (50%), test (50%)
• Primary metric: Funnel conversion (pricing_page → checkout)
• Status: Draft (ready to launch)
• URL: https://us.posthog.com/project/ /experiments/789

Example 4: Error investigation

Prompt: "What are the top 5 errors in my project this week and how many users are affected?"

What happens:

1. The query-error-tracking-issues-list tool fetches error groups sorted by occurrence count
2. Returns error details including affected user counts

Expected output:

Top 5 errors this week:

1. TypeError: Cannot read property 'id' of undefined

• Occurrences: 1,247
• Users affected: 89
• First seen: 2 days ago

1. NetworkError: Failed to fetch

• Occurrences: 856
• Users affected: 234
• First seen: 5 days ago

...

Quick prompts

For simpler queries, you can use shorter prompts:

• "What feature flags do I have active?"
• "Show me my LLM costs this week"
• "List my dashboards"
• "What events are being tracked?"

Feature Filtering

You can limit which tools are available by adding query parameters to the MCP URL. If no features are specified, all tools are available. When features are specified, only tools matching those features are exposed.

https://mcp.posthog.com/mcp?features=flags,workspace,dashboards

Available features:

| metrics | Metrics