PostHog

PostHog

This connector works with PostHog's private REST API on the app host (https://us.posthog.com, https://eu.posthog.com or your self-hosted address), signed in with a personal API key as the user who created it: the AI sees and changes what that user can. It covers the current user, organizations and projects, read-only SQL queries (HogQL) and insight queries (trends, funnels, retention), persons, saved insights (read, create, change), dashboards, feature flags (read, create, change), cohorts, annotations and experiments.

Setup (about 3 minutes)

1. In PostHog open Settings -> User -> Personal API keys (US Cloud: https://us.posthog.com/settings/user-api-keys, EU Cloud: https://eu.posthog.com/settings/user-api-keys) and click + Create a personal API key.
2. Give it a label (for example "AnythingMCP") and choose the organization and project access: all, one organization, or specific projects. A key limited to specific projects cannot list organizations or projects (PostHog only allows such keys on project endpoints); posthog_get_current_user still works and names the current project.
3. Pick the scopes. For every tool here: user:read, organization:read, project:read, query:read, person:read, insight:read, insight:write, dashboard:read, feature_flag:read, feature_flag:write, cohort:read, annotation:read, annotation:write and experiment:read.
4. Copy the key right away (it starts with phx_; PostHog shows it only once) and paste it into POSTHOG_PERSONAL_API_KEY.
5. Set POSTHOG_HOST to the address you open PostHog at: https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud, or your own address for a self-hosted instance (no trailing slash, no path). The ingestion hosts us.i.posthog.com and eu.i.posthog.com only take events and are refused here. A key works only on the cloud region where it was created.

Read-only setup: create the key with only the :read scopes above and switch off posthog_create_insight, posthog_update_insight, posthog_create_feature_flag, posthog_update_feature_flag and posthog_create_annotation. posthog_delete_insight, posthog_delete_feature_flag and posthog_delete_annotation are installed switched off. Queries never change data.

Project ids: every project tool takes project_id, the number in the PostHog URL (/project/12345/...) and under Settings -> Project -> General. Call posthog_get_current_user first: it returns the current project and the projects of the current organization; posthog_list_projects lists the projects of any organization from posthog_list_organizations. @current is accepted as project_id and organization_id, but it means the project or organization the user last opened in the PostHog app, which can change under you, and a key scoped to other projects gets 403 for it. Prefer the number.

Queries

• posthog_run_hogql_query runs one HogQL statement (PostHog's SQL, ClickHouse-based) through the query endpoint. HogQL only accepts SELECT, so the tool cannot change data even though it is a POST.
• Main tables: events (event, timestamp, distinct_id, person_id, properties), persons (id, created_at, properties), person_distinct_ids, sessions and groups. Read properties with dot notation (properties.$browser, properties.$current_url, person.properties.email) or brackets for odd names (properties['$feature/new-checkout']).
• Always filter on time, e.g. WHERE timestamp >= now() - INTERVAL 7 DAY; unfiltered scans of events are slow and eat the read budget. Date literals are read in the project's timezone, not UTC: write toDateTime('2026-10-01 00:00:00', 'UTC') for an exact instant.
• Without a LIMIT PostHog returns 100 rows; with one, up to 50,000. OFFSET is refused with 400 for API keys: page by timestamp (events) or id (persons) instead, e.g. WHERE timestamp < '<last timestamp seen>' ORDER BY timestamp DESC LIMIT 500. Answers over 200 KB are cut and marked _truncated.
• Put user-supplied text in values and refer to it as {name} in the query instead of pasting it into the SQL.
• posthog_run_insight_query runs PostHog's own insight calculations: TrendsQuery, FunnelsQuery, RetentionQuery, StickinessQuery, LifecycleQuery and PathsQuery. Use it for funnels and retention, which are hard to write in SQL. Conversion and retention percentages are not in the answer: compute them from the count values.
• The query endpoint is meant for ad hoc analysis, not exports: PostHog may throttle or refuse queries that page through large tables. For bulk data use PostHog's batch exports.

Insights and dashboards: posthog_list_insights returns metadata only by default; posthog_get_insight adds the last cached result (refresh force_cache, the default, never calculates; blocking recalculates when the cache is stale). An insight's query is usually {"kind": "InsightVizNode", "source": {"kind": "TrendsQuery", ...}}, or {"kind": "DataVisualizationNode", "source": {"kind": "HogQLQuery", "query": "..."}} for a SQL insight. posthog_get_dashboard returns the dashboard with its tiles and their insights, cut at 200 KB.

Feature flags: flags decide what live users see. Before posthog_create_feature_flag, posthog_update_feature_flag or posthog_delete_feature_flag, show the user the flag key, active and the rollout and wait for an explicit yes. Targeting lives in filters.groups, a list of release conditions each with properties and rollout_percentage (0 to 100); a new flag is safest with active false or a rollout of 0. Pass the flag's version from your last read when changing it: flags on PostHog's newer configuration require it, and a stale version is refused with 409 instead of overwriting someone else's change.

Deleting: PostHog never hard-deletes insights, flags or annotations through the API; the delete tools set deleted to true and the item can be restored in the PostHog app.

Pagination: list tools take limit and offset and return count (when PostHog computes it), next and previous (full URLs; raise offset by limit to follow next, which is null on the last page) and results. An empty project answers with an empty results list.

Rate limits (per organization, shared by every key and user): 480 requests per minute and 4,800 per hour for ordinary reads and writes; 240 per minute and 1,200 per hour for analytics endpoints such as persons and insight calculations; the query endpoint allows 240 per minute and 2,400 per hour, at most 3 queries running at once per project, and draws on an hourly read budget per project (smaller on the free plan). Over a limit PostHog answers 429; an exhausted read budget says api_queries_budget_exceeded with Retry-After, while cached results keep working.

Errors: 401 ("Personal API key found in request Authorization header is invalid.") means the key is wrong, deleted, or from the other cloud region (check POSTHOG_HOST). 403 "API key missing required scope 'x'" names the scope to add (scopes can be changed on the key later); other 403s mean the key is limited to other projects or organizations, or the organization does not allow personal API keys for members. 404 "Project not found." is a wrong project_id or one the user cannot see. 400 names the invalid field; for HogQL it carries the parser error. 409 on a flag is a stale version.

Out of scope here: capturing events or setting person properties (that is the public ingestion API), deleting persons, the deprecated raw events list endpoint (use posthog_run_hogql_query on events instead), session replays, surveys, creating or editing dashboards, cohorts and experiments, actions and the data warehouse setup, batch exports, and organization, member and billing administration.