posthog-toolkit-mcp

An MCP server for PostHog, on PostHog Cloud or a self-hosted instance: HogQL queries, event and property definitions, session replays and the REST API — with guards that keep an agent from sending the API key elsewhere or writing by accident.

Tools

| Tool | What it does | |---|---| | posthog_query | Runs a HogQL query. Refuses insight placeholders like {filters} before sending, and says when PostHog cut the results at its default LIMIT 100. | | posthog_event_definitions | Event names seen in the project, with last-seen time; optional substring search. | | posthog_property_definitions | Event or person property names with their types. | | posthog_replays | Session recordings of a distinct_id in a time window, newest first, with links. | | posthog_projects | Projects of the organization. Works with personal API keys scoped to specific projects. | | posthog_api_get | GET any PostHog REST endpoint; {project_id} in the path is filled in. | | posthog_api_request | Any method, including writes. Registered only with POSTHOG_ALLOW_WRITE. |

Configuration

| Variable | | |---|---| | POSTHOG_HOST | Required. https://us.posthog.com, https://eu.posthog.com, or your self-hosted URL. | | POSTHOG_API_KEY | Required. A personal API key (phx_...). A project token (phc_...) is rejected at startup — it can only send events. | | POSTHOG_PROJECT_ID | Default project for the tools and for {project_id} in paths. | | POSTHOG_ALLOW_WRITE | 1, true or yes registers posthog_api_request. Off by default. | | POSTHOG_MAX_RESPONSE_CHARS | Cap on a tool response. Default 100000. | | POSTHOG_TIMEOUT_MS | Request timeout. Default 120000. |

The key needs read access to the project (and user read access for posthog_projects; without it the tool falls back to the organization project list).

Install

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "posthog-toolkit-mcp"],
      "env": {
        "POSTHOG_HOST": "https://posthog.example.com",
        "POSTHOG_API_KEY": "${POSTHOG_API_KEY}",
        "POSTHOG_PROJECT_ID": "1"
      }
    }
  }
}

In Claude Code this block goes into the project's .mcp.json; keep the key itself out of the file, e.g. in the env block of .claude/settings.local.json, and pin the version ([email protected]) so every machine runs the same server.

Security

• Read-only by default; writes need POSTHOG_ALLOW_WRITE.
• Requests go only to the POSTHOG_HOST origin: a path like //other-host/... is refused before the API key could leave with it.
• Project ids are validated as numbers before they reach a URL.

Development

npm install
npm run typecheck  # tsc --noEmit
npm run build      # esbuild bundles src/index.ts into dist/server.mjs with no runtime dependencies
npm run smoke      # stdio checks: configuration errors, tool list, guards that fire before any network call
npm run check      # all three

| File | | |---|---| | src/index.ts | Entry point: builds the server from the environment and connects stdio. | | src/config.ts | Reads and validates environment variables. | | src/posthog-client.ts | PostHog API client; refuses paths that would leave POSTHOG_HOST. | | src/schemas.ts | Zod input schemas of the tools; handler argument types are inferred from them. | | src/server.ts | Tool registration and result formatting. | | src/hogql.ts | HogQL literals, insight placeholder detection, the recordings query. |

The bundle is a single file on purpose: npx starts it without installing any dependencies.

License

MIT — see LICENSE. Dependencies bundled into dist/server.mjs keep their own licenses, listed in THIRD_PARTY_NOTICES.md.