Connect PostHog to Claude Code

Run HogQL queries and read insights, events, flags, cohorts and recordings. Add Toolspoke to Claude Code once and it can use 12 PostHog actions. Your PostHog credential stays in Toolspoke, and you choose which actions Claude Code may call.

Set it up in Claude Code

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. Install PostHog and connect it

    Add PostHog to a project in your Toolspoke workspace.

    Personal API key. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Personal API key
    PostHog → Settings → Personal API keys. Give it the read scopes you need (query, insight, event, person, feature_flag, cohort, session_recording, dashboard) and scope it to the projects this install may reach.
    Project ID
    The numeric project id from PostHog → Settings → Project. It is in the dashboard URL: /project/12345/.
  3. Choose what Claude Code may do

    All 12 actions start on. Switch off the one action that changes something in PostHog, and Claude Code gets a refusal if it tries.

What you can ask Claude Code for

A few of the PostHog actions that only read, so they are safe to try first.

  • Run a HogQL query
  • List raw events in a time window, newest first, with their properties and the person who sent them
  • Fetch one person by their numeric PostHog id, with every property PostHog holds and all of their distinct ids
  • List the project's feature flags with their key, name, active state, rollout conditions and variants

What Claude Code can do in PostHog

11 actions read and one deletes or permanently changes something.

Reads

  • Run query

    Run a HogQL query. ClickHouse SQL over PostHog's own tables, and return the rows with their column names. This is the operation to reach for whenever a question is not already answered by a saved insight: `select properties.$current_url, count() from events where event = '$pageview' and timestamp > now() - interval 7 day group by 1 order by 2 desc limit 20`. The tables are events, persons, sessions, groups and person_distinct_ids. HogQL is select-only, which is why this is a read. Always include a LIMIT: the rows come back verbatim. Response payloads are kept out of the audit log because they can contain person properties.

  • List insights

    List the saved insights in the project, the charts people have built and kept, with their id, short id, name, description and type. Use it to find out what the team already measures before writing a HogQL query for it, and to get the id that get_insight needs. Returns definitions, not results.

  • Get insight

    Fetch one saved insight by its numeric id, including its full query definition and its most recent computed result. Use it after list_insights when you want the numbers a chart shows, rather than rebuilding the chart's logic yourself in run_query.

  • List events

    List raw events in a time window, newest first, with their properties and the person who sent them. Useful for looking at exactly what one user did, or checking that a newly instrumented event is arriving. PostHog treats this endpoint as legacy and it is narrow: without `after` you only get the last 24 hours, the window between `after` and `before` cannot exceed a year, and paging stops at 50,000. For anything aggregate, use run_query instead. Payloads are kept out of the audit log because event properties carry personal data.

  • List persons

    Search the people PostHog has identified, by email, distinct id or free text, and return their properties and distinct ids. Call this first when you need the person id that get_person takes. This returns other people's personal data, so the response is never written to the audit log.

  • Get person

    Fetch one person by their numeric PostHog id, with every property PostHog holds and all of their distinct ids. Get the id from list_persons, a distinct id is not a person id. This returns another person's personal data, so the response is never written to the audit log.

  • List feature flags

    List the project's feature flags with their key, name, active state, rollout conditions and variants. Call this before get_feature_flag or update_feature_flag, those take the numeric flag id, which only this returns, not the human-readable key. It is also the cheapest call here, so it is the connection's health check.

  • Get feature flag

    Fetch one feature flag by numeric id, with its complete filter groups, rollout percentages, variants and payloads. Read this before update_feature_flag: an update replaces the fields you send, so you need to know what is there now to avoid dropping a targeting rule.

  • List cohorts

    List the project's cohorts, named groups of people defined by properties or behaviour, with their id, name, description and member count. Use it to find the cohort id you can then reference from a HogQL query in run_query, or to see how the team already segments its users.

  • List session recordings

    List session replay recordings with their id, duration, start time, click and keypress counts and the person they belong to. Returns the index only, the replay data itself is not available through this endpoint. Use it to find a recording worth watching in PostHog, then open it there. Recordings are other people's browsing sessions, so the response is never written to the audit log.

  • List dashboards

    List the project's dashboards with their id, name, description and the insights on each. Use it to see how the team organises its reporting, and to find which insight ids belong to a dashboard before calling get_insight on them.

Deletes or permanently changes

  • Update feature flag

    Change a feature flag: turn it on or off, rename it, archive it, or replace its targeting filters. Destructive because it changes what real end users see the moment it lands, flipping `active` can expose an unfinished feature to everyone, or switch one off underneath people mid-session, and because `filters` replaces the whole targeting object rather than merging into it. Call get_feature_flag first and send back the full filters object with your change applied, or you will silently delete the existing rollout rules.

PostHog in Claude Code: questions

Does Claude Code see my PostHog credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Claude Code from changing things in PostHog?

Yes. Each of the 12 actions can be switched off for a project. Turn off the one that changes something and Claude Code can only read.

Will 12 actions crowd Claude Code's context?

No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the PostHog action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Can I add it once for every project?

Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.

What does it cost?

Tool calls are free on every plan, and a PostHog call does not run in a sandbox, so it bills nothing.

Try PostHog in Claude Code

Free to start, and tool calls cost nothing on any plan.