@bossforce.ai/mcp-posthog

MCP server for the PostHog API. List projects, run HogQL queries, list saved insights, and capture custom events. A good fit for pulling product-analytics data into an agent and recording events.

Credentials

| Env | How to obtain | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | POSTHOG_HOST | Region API host: https://us.posthog.com or https://eu.posthog.com (or your self-hosted URL). Optional — defaults to US Cloud. | | POSTHOG_PERSONAL_API_KEY | Personal API key (phx_…) from Settings > Personal API keys, with the project:read, query:read and insight:read scopes. | | POSTHOG_PROJECT_API_KEY | Project API token (phc_…) from Settings > Project. Only needed for capture_event. |

Reads authenticate with the personal API key as a Bearer token against the private host (POSTHOG_HOST). Credentials are read lazily, so the server boots and answers tools/list without them; calls fail with an auth error until the required key is set.

Tools

| Tool | Arguments | Returns | | --------------- | --------------------------------------------------- | ------------------------------- | | list_projects | — | { count, next, results } | | query | project_id, query | HogQL { columns, results, … } | | list_insights | project_id, search?, limit?, offset? | { count, next, results } | | capture_event | event, distinct_id, properties?, timestamp? | ingestion acknowledgement |

Responses are PostHog's native JSON payloads, returned as structuredContent.

Project id and event capture

query and list_insights are project-scoped: call list_projects first to get the numeric project_id. query wraps your statement as { query: { kind: "HogQLQuery", query } }.

capture_event is different: it posts to the public ingestion host (the same host with an .i. infix, e.g. us.i.posthog.com) and authenticates with the project API token (POSTHOG_PROJECT_API_KEY) sent in the request body — not the personal key.

Develop

pnpm --filter @bossforce.ai/mcp-posthog build
pnpm --filter @bossforce.ai/mcp-posthog test

Regenerate the tools/list snapshot after an intentional signature change:

UPDATE_SNAPSHOTS=1 pnpm --filter @bossforce.ai/mcp-posthog test