Skip to main content
Glama
Sign In
posthog-toolkit-mcp

posthog-toolkit-mcp

by deadrime
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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.

Related MCP server: pg-readonly-mcp

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 (posthog-toolkit-mcp@0.1.0) 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.

Available Tools

6 tools
posthog_api_getGET a PostHog API endpointA
Read-only

GET any PostHog REST endpoint for what HogQL does not cover: feature flags, insights, dashboards, experiments, cohorts. {project_id} in the path is replaced with the default project, e.g. /api/projects/{project_id}/feature_flags/

Inputs: path (required), params.

posthog_event_definitionsList event namesA
Read-only

Event names seen in a project, with when each was last seen. Use it instead of guessing event names in HogQL.

Inputs: limit, offset, search, project_id.

posthog_projectsList projectsA
Read-only

Projects of the organization with their ids. Works with API keys scoped to specific projects.

Inputs: no named parameters.

posthog_property_definitionsList property namesA
Read-only

Event or person property names in a project, with their types. Use it instead of guessing property names in HogQL.

Inputs: type, limit, offset, search, +1 more.

posthog_queryRun a HogQL queryA
Read-only

Runs a HogQL (ClickHouse SQL dialect) query: tables events, persons, sessions, groups, raw_session_replay_events. Example: SELECT event, count() FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY 2 DESC LIMIT 20.

Inputs: query (required), project_id.

posthog_replaysFind session replaysA
Read-only

Session recordings of one distinct_id in a time window, newest first, with links to watch them. Recordings older than the instance retention are gone. Naive timestamps are read in the project timezone.

Inputs: distinct_id (required), to, from, limit, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct area—definitions, projects, HogQL querying, replays, and generic REST access—so an agent can usually choose correctly. The only mild overlap is between posthog_query and posthog_api_get, but the HogQL vs REST distinction is clearly drawn.

    Naming Consistency3/5

    All tools share a posthog_ prefix and snake_case, but the pattern is mixed: event_definitions, projects, property_definitions, and replays are resource nouns, while posthog_query is an operation and posthog_api_get introduces a verb suffix. It is readable but not a consistent verb_noun scheme.

    Tool Count5/5

    Six tools cover the core PostHog introspection and querying use cases without padding. The generic posthog_api_get tool avoids the need for many narrowly-scoped REST endpoint tools.

    Completeness4/5

    Event/property definitions, project selection, HogQL querying, session replays, and a generic REST GET cover the main read and analysis workflows. Write/update operations are not exposed through the REST wrapper, but that appears intentionally out of scope for this query-oriented toolkit.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-read-only-sql

      lukleh
      A
      license
      Not graded
      quality
      B
      maintenance
      Provides secure read-only SQL access to PostgreSQL and ClickHouse databases with built-in safety features like read-only enforcement, timeouts, and managed result files.
      MIT

    • pg-readonly-mcp

      MadlyFriese
      F
      license
      A
      quality
      D
      maintenance
      Enables read-only exploration of a Postgres database using natural language, with multiple safety layers to prevent any modifications.
      5
      -

    • mcp-server-postgres

      ofershap
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query PostgreSQL, inspect schemas, and explain queries, designed for local and development databases with read-only safety by default.
      45 npm
      MIT

    • mcp-postgres

      4l3x31s
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to inspect PostgreSQL schemas, run read-only queries and explain plans, and, when explicitly permitted, execute writes and DDL on a per-project database with layered safety controls.
      MIT