PPToGoVisit PPToGo →

PostHog MCP: setup, tools, and where it actually helps

August 22, 2026 · PPToGo Team

You opened Claude Desktop, ran the posthog mcp command, and now an LLM is reading your product analytics the same way a teammate would. That quiet handoff is the whole point of the PostHog MCP server: it lets an AI client pull feature flags, events, and dashboards out of PostHog and answer questions about them in plain English. This guide walks through what it unlocks, how to install it in Claude and Codex, and the edges where the integration frays — so you can decide if the PostHog MCP server belongs in your stack.

What the PostHog MCP integration unlocks

The PostHog MCP server is a thin wrapper around PostHog's APIs, exposed through Anthropic's Model Context Protocol. Once an MCP-aware client connects, it can list the available tools, ask for them, and feed the responses back to the model. In practice, this means a developer or PM sitting in Claude (or any other MCP host) can ask "how many users hit the checkout funnel yesterday?" and watch the assistant call a tool, retrieve data, and answer — no copy-pasting JSON, no dashboard hopping.

Concrete workflows the server enables:

None of this is magic on its own — PostHog's REST and query APIs already do the work. The MCP server just packages them as tools the model can call. The unlock is conversational access, not new data.

Prerequisites and supported plans on both sides

Before you install, check two things: which PostHog plan you're on, and which MCP host you want to drive.

Pro tip: Generate one API key per MCP client, label it (e.g. claude-desktop-macbook), and revoke it the day you stop using that client. A leaked key gives full project read/write.

Step-by-step setup

The canonical install lives in the PostHog GitHub repo under plugins/mcp. The PostHog MCP docs mirror those instructions. Total time: roughly five minutes on a clean machine.

  1. Generate a personal API key. In PostHog, open Settings → Personal API Keys, click Create personal API key, give it a label, and pick All access (read-only is enough if you only want analytics). Copy the key — it is shown once.
  2. Locate your client's MCP config. For Claude Desktop, this is ~/.config/claude-desktop/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, and %APPDATA%\Claude\claude_desktop_config.json on Windows. Codex CLI uses ~/.codex/config.toml.
  3. Add the PostHog server entry. Paste a block of the shape below, replacing the values for your environment. The env keys accept either a Cloud project key or a self-hosted host string.
    {
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "@posthog/mcp-server"],
      "env": {
        "POSTHOG_API_KEY": "phx_xxx",
        "POSTHOG_HOST": "https://us.i.posthog.com"
      }
    }
  }
}
  4. Restart the client. Claude Desktop only reads MCP config on launch. Close it fully — including the tray icon — and reopen.
  5. Verify the tool list. Open the chat, and ask: "What PostHog tools do you have access to?" The model should respond with the list of MCP tools it can now call. If the response is empty, jump to the Limits, edge cases, and known gotchas section.
  6. Run a smoke query. Ask: "How many distinct users triggered the checkout_completed event in the last 7 days?" The model should call the events tool, return a number, and cite the run. That ends the install.

No OAuth consent screen is involved when you use a personal API key. If you self-host and want SSO-scoped access instead, the PostHog MCP docs describe a per-user OAuth variant that triggers a browser consent flow on first connect.

The joint workflow in action

Picture this: a PM drops a Slack message — "did the new onboarding nudge actually move the activation metric?" You do not need to log into PostHog. You open Claude Desktop, the PostHog MCP server is wired up, and you ask the model to compare last week's activation rate against the prior two-week baseline, segmented by whether the user saw the nudge.

  1. The client calls the list_events tool to confirm the event names exist.
  2. It calls the trend query tool with a date range and a property filter for seen_nudge=true.
  3. It repeats the query with seen_nudge=false as the property filter.
  4. It returns a short write-up with the delta, plus the SQL it actually ran, so you can paste it into a saved insight later.

Latency in this path is dominated by PostHog's query engine, not the MCP transport. Expect two to ten seconds per tool call on Cloud, occasionally longer for cohort queries that hit large fact tables. Self-hosted latency tracks whatever your ClickHouse or Postgres backend delivers. Each tool call round-trips through the model's context, so a verbose answer costs more input tokens than a chart screenshot ever would — keep that in mind for cost modelling.

Limits, edge cases, and known gotchas

The PostHog MCP server is a young integration and a handful of rough edges show up in real use:

Common questions

Does PostHog have an MCP server?

Yes. PostHog ships an officially maintained MCP server on GitHub. It works with any MCP-compatible client — Claude Desktop is the most documented host, but Codex CLI, Open WebUI, and custom clients can connect to the same transport.

Is the PostHog MCP server free?

The server code is open source and free to install. You still pay for whatever PostHog plan your project sits on (free tier works for low-volume use) and for any tokens your LLM client consumes answering queries. There is no separate MCP licence fee.

Can I use the PostHog MCP server with Codex CLI?

Yes. Codex CLI reads MCP server entries from ~/.codex/config.toml. The same @posthog/mcp-server package works; you point POSTHOG_HOST at either the US or EU Cloud region, or at your self-hosted URL, and the tools appear in the model the same way they do in Claude Desktop.

What tools does the PostHog MCP server expose?

Typical tool set: list and inspect events, run HogQL/trend queries, list feature flags and their rollout state, fetch persons and their properties, read session replays by URL, list dashboards, and search PostHog's own docs. Exact names shift with each server release, so verify against your installed version.

How do I install the PostHog MCP server on Claude Desktop?

Add the JSON config block above to your platform-specific claude_desktop_config.json, set the POSTHOG_API_KEY and POSTHOG_HOST environment values, restart Claude Desktop, and ask the assistant to list its PostHog tools to confirm.

Where are the official PostHog MCP docs?

PostHog hosts them at posthog.com/docs/mcp. The GitHub README in posthog/posthog/plugins/mcp carries the same setup instructions plus the changelog.

Is there an analytics-only mode for the PostHog MCP server?

You can scope behaviour with the API key. A read-only key restricts the assistant to query tools and skips flag toggles or person mutations. That mode is the safest default for shared chat clients.

Once the server is wired in, the day-to-day experience is a chat thread that already knows your product. If you sell software that touches PostHog data — or are building AI tools that integrate with it — browse the PPToGo product catalogue for related tooling and creator shops already shipping in that space.

Ready to try PPToGo?

Sell digital products smoothly, globally.

Visit PPToGo →
← All articles