PostHog MCP for Claude Code: Setup and Tools

The PostHog MCP server lets Claude Code read and change your PostHog project from the terminal: query analytics, run SQL, manage feature flags, and dig into error stack traces without opening the PostHog app. It's a hosted server, so there's nothing to run locally. One command connects it.

Here's the short version:

• Server URL: https://mcp.posthog.com/mcp — one endpoint for both US and EU Cloud. You're routed to your region based on the account you log in with.
• Fastest install: npx @posthog/wizard mcp add
• Manual install for Claude Code: claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user
• Auth: OAuth in the browser by default. A personal API key works for clients without OAuth.
• Cost: connecting and calling tools is free, per PostHog. Normal PostHog usage billing still applies, and a few AI-powered tools can bill as PostHog AI spend.
• Safety: PostHog itself warns about prompt injection. Read-only mode and tool filtering are one URL parameter away.

Everything below comes from PostHog's MCP documentation and its Claude Code page, checked in October 2026.

Three ways to add the PostHog MCP server to Claude Code

PostHog documents three install paths for Claude Code. They all end at the same hosted server; they differ in what else comes along.

The wizard

The PostHog Wizard is an npm package that writes the MCP config for you. PostHog says it can install into PostHog Desktop, Cursor, Claude Code, Claude Desktop, Codex, VS Code, and Zed. Run it from any directory:

npx @posthog/wizard mcp add

This is the path PostHog recommends if you're not sure. OAuth "works out of the box with the wizard," in the docs' words.

The Claude Code plugin

PostHog also ships an official AI plugin for Claude Code, Codex, Cursor, and other clients:

claude plugin install posthog

After it installs, run /mcp inside Claude Code, pick the PostHog server, and finish the login in your browser. The plugin's README also documents a marketplace route (claude plugin marketplace add PostHog/ai-plugin, then claude plugin install posthog@posthog) if the short form doesn't resolve on your setup.

The plugin adds slash commands such as /posthog:flags, /posthog:insights, /posthog:errors, and /posthog:experiments. Pick it if you want quick commands on top of the raw tools.

Manual setup with claude mcp add

If you'd rather see exactly what gets written, this is the command from PostHog's Claude Code page:

claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user

Three things to notice:

• --transport http is required. It's a remote HTTP server, not a local process.
• -s user makes the server available in every project on your machine. Drop it and Claude Code uses its default local scope, which ties the server to the current project only.
• There's no key in the command. The first time Claude Code calls a PostHog tool, you're prompted to log in.

If you manage several MCP servers, our guide to Claude Code MCP server configuration covers scopes, .mcp.json, and how to check what's connected.

Regions, accounts, and API keys

US vs EU

You don't pick a region in the URL. PostHog's auth server routes you to US or EU Cloud based on the account you sign in with. The FAQ adds one catch: if you have accounts in both regions, you need two separate connections, because one connection signs in as one account.

OAuth or a personal API key

OAuth is the recommended path, and you don't need to create a key for it. If your client can't do OAuth, PostHog's FAQ says to create a personal API key with the MCP Server preset (which scopes it to a specific project) and send it as an Authorization: Bearer header. In Claude Code, the general syntax for a header on an HTTP server is --header, as shown in Claude Code's MCP docs.

Several projects or organizations

One connection has one active organization and project. Agents can move between them with the switch-organization and switch-project tools, but PostHog warns that "a wrong assumption can send a write to the wrong project."

The fix is pinning. Add an x-posthog-project-id header (or a project_id query parameter), and the server removes the switch tools so the agent can't wander. If you work across projects regularly, add one named connection per project.

What tools the PostHog MCP server exposes

PostHog describes the server as exposing "feature flags, product analytics, error tracking, experiments, SQL queries, CDP, surveys, and more." The full MCP tools reference runs to hundreds of tools. The ones you'll use most from Claude Code fall into a few groups:

CLI mode vs tools mode

You won't see hundreds of tool definitions in Claude Code, and that's deliberate. PostHog's FAQ explains two modes:

• CLI mode exposes one exec tool. The agent uses it to search for a tool, inspect its schema, and call it on demand. Claude Code defaults to this mode, and it keeps the context window small.
• Tools mode registers every tool individually. Cursor defaults to this one.

You can force either with ?mode=cli or ?mode=tools on the URL. For Claude Code, the default is the right call. Loading hundreds of tool schemas up front is exactly the context bloat our best MCP servers guide warns about.

Four prompts to try first

Once the server is connected, you talk to it in plain English. These four cover reading, querying, debugging, and writing.

1. Audit stale flags against your code

List every feature flag that's rolled out to 100% of users. Then search this repo for each flag key and tell me which ones are safe to remove.

This is where PostHog in Claude Code beats PostHog in a browser tab: the agent sees the flag list and your codebase in one session.

2. Debug the top error

What are the five most frequent errors in the last 24 hours? For the top one, open the file and line from its stack trace and suggest a fix.

3. Ad-hoc SQL

Write and run a SQL query: daily signups for the past 14 days, broken down by utm_source. Show the query before you run it.

Asking to see the query first is a good habit. You'll catch a wrong event name before it costs you a confusing answer.

4. A write action

Create a feature flag called new-onboarding-flow, rolled out to 10% of users. Don't enable it for anyone else.

This one changes your project, so read the tool call before you approve it. Which leads to the safety settings.

Cost: what's free and what isn't

PostHog's FAQ is explicit: "Connecting to the MCP server and calling its MCP tools is free." Two qualifiers follow:

• Standard PostHog usage and billing still apply to the data your queries touch.
• Some tools use LLMs internally and "may be billed as PostHog AI spend." These AI-powered tools only appear when AI data processing is enabled in your organization settings. When it's off, they're filtered out of your client entirely.

There are also rate limits on the MCP server itself, counted per credential. PostHog lists the current numbers in the FAQ; check there rather than relying on a figure copied into a blog post. Note that every request counts, including listing tools and opening a session.

Your Claude Code usage is billed separately by Anthropic, under whatever plan or API key you use for Claude Code.

Safety: prompt injection, read-only mode, and filters

PostHog puts this warning on its Claude Code page:

Be mindful of prompt injection – LLMs can be tricked into following untrusted commands, so always review tool calls before executing them.

That matters more than it sounds. Your PostHog data contains strings other people typed: survey responses, support tickets, event properties, error messages. Any of them can carry instructions aimed at an agent. If the agent reads that text and has write tools available, a malicious string can steer it. Our post on MCP security risks walks through how that attack works.

PostHog gives you three controls, all set on the URL or as headers:

For example, a read-only connection for analysis work would look like this (the same documented command, with PostHog's documented query parameter added):

claude mcp add --transport http posthog-ro "https://mcp.posthog.com/mcp?readonly=true" -s user

A sensible setup: a read-only connection for everyday questions, and a separate, pinned, write-capable connection you enable only when you actually want the agent to change flags or experiments. Keep Claude Code's own permission prompts on for PostHog write tools too. Approving a flag rollout should be a decision, not a reflex.

One more data point from PostHog: the server is a proxy. It "does not store your analytics data"; queries run against your project and results go straight to your client.

FAQ

Is the PostHog MCP server free?

Connecting and calling tools is free, according to PostHog. Your normal PostHog usage billing still applies, and AI-powered tools may bill as PostHog AI spend. Those tools only appear if AI data processing is enabled.

What's the PostHog MCP server URL?

https://mcp.posthog.com/mcp. The same URL serves US and EU Cloud; your login decides the region.

Do I need an API key for PostHog MCP in Claude Code?

No. Claude Code supports OAuth, and you log in through the browser the first time you use a tool. A personal API key with the MCP Server preset is the fallback for clients that can't do OAuth.

Can I stop Claude Code from changing my PostHog project?

Yes. Add ?readonly=true to the server URL, or send the x-posthog-read-only: true header. Write tools disappear from the tool list.

Does the PostHog MCP server work with self-hosted PostHog?

PostHog's MCP docs describe the hosted endpoint routing to US and EU Cloud. They don't document a self-hosted setup, so assume Cloud unless PostHog says otherwise.

Plugin or plain MCP server?

Same tools either way. The plugin adds slash commands and skills. If you only want the tools, the manual claude mcp add command is the smallest footprint.

Wrapping up

• One hosted URL, https://mcp.posthog.com/mcp, covers both regions.
• Install with the wizard, the posthog plugin, or one claude mcp add line.
• Claude Code gets a compact exec tool by default instead of hundreds of schemas.
• Calls are free per PostHog; usage billing and PostHog AI spend still apply.
• Treat your PostHog data as untrusted input. Use read-only mode and pinning.

If you'd like to run a working Claude Code setup like this without rebuilding the configuration yourself, Taku mirrors AI setups into a desktop workspace and runs them, so you start from something that already works. Taku is in Beta, and the Mac app is available now.