Posthog MCP Server

What is Posthog MCP Server about?

The Posthog MCP Server acts as a bridge between AI models and a PostHog instance, exposing data‑driven tools (flags, insights, errors, dashboards, experiments, LLM analytics, docs search) through the Model Context Protocol. This lets developers and AI assistants retrieve actionable information without writing custom API calls.

How to use Posthog MCP Server?

Quick install – run npx @posthog/wizard@latest mcp add to automatically add the server configuration to supported desktop clients (Cursor, Claude, VS Code, Zed, etc.).
Manual install – add a JSON snippet to the client’s mcpServers config, providing your personal PostHog API key via the POSTHOG_AUTH_HEADER environment variable.
Docker install – build the Docker image with pnpm docker:build or docker build -t posthog-mcp . and run it using the supplied docker command configuration.
Replace the default URL (https://mcp.posthog.com/mcp) with http://localhost:8787/mcp when developing locally (pnpm run dev).

Key features of Posthog MCP Server

Feature‑flag management – list, create, and modify flags.
Workspace tools – organization and project handling.
Error‑tracking – fetch recent errors and debugging data.
Dashboard & insights – retrieve dashboards, run insight queries, and execute SQL‑style analytics.
Experiments – access A/B testing experiment details.
LLM analytics – monitor LLM usage and cost breakdowns.
Documentation search – query PostHog documentation via Inkeep (requires API key).
Feature filtering – limit exposed tools with URL query parameters (e.g., ?features=flags,workspace).
Self‑hosted support – set POSTHOG_BASE_URL to point to a custom PostHog instance.

Use cases of Posthog MCP Server

AI‑driven troubleshooting – ask an assistant “What are my most common errors?” and get a concise list.
Feature‑flag automation – programmatically add or toggle flags during a deployment pipeline.
Cost monitoring – retrieve weekly LLM spend to keep budgets in check.
Insight generation – ask “Show me the conversion funnel for the signup flow” and receive the insight data.
Documentation assistance – let AI retrieve relevant PostHog docs while coding.

FAQ from the Posthog MCP Server

Q: Do I need Node.js installed locally? A: No. The Docker installation runs the server in a container, and the npx quick‑install method does not require a permanent Node environment.

Q: What environment variables are required? A: POSTHOG_AUTH_HEADER (Bearer token) is mandatory. POSTHOG_REMOTE_MCP_URL is optional and defaults to https://mcp.posthog.com/mcp. For self‑hosted setups, set POSTHOG_BASE_URL.

Q: Can I restrict which tools are exposed? A: Yes. Append ?features= with a comma‑separated list to the MCP URL.

Q: How do I add new tools? A: Follow the guide in typescript/src/tools/README.md and run pnpm run schema:build:json to update shared schemas.

Q: Is any sensitive data stored outside my region? A: The server runs on a Cloudflare worker; it does not persist sensitive data outside your cloud region.

PostHog MCP

Documentation: https://posthog.com/docs/model-context-protocol

Use the MCP Server

Quick install

You can install the MCP server automatically into Cursor, Claude, Claude Code, VS Code and Zed by running the following command:

npx @posthog/wizard@latest mcp add

Manual install

Obtain a personal API key using the MCP Server preset here.
Add the MCP configuration to your desktop client (e.g. Cursor, Windsurf, Claude Desktop) and add your personal API key

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.posthog.com/mcp", // You can replace this with https://mcp.posthog.com/sse if your client does not support Streamable HTTP
        "--header",
        "Authorization:${POSTHOG_AUTH_HEADER}"
      ],
      "env": {
        "POSTHOG_AUTH_HEADER": "Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}"
      }
    }
  }
}

Docker install

If you prefer to use Docker instead of running npx directly:

Build the Docker image:

pnpm docker:build
# or
docker build -t posthog-mcp .

Configure your MCP client with Docker:

{
  "mcpServers": {
    "posthog": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env",
        "POSTHOG_AUTH_HEADER=${POSTHOG_AUTH_HEADER}",
        "--env",
        "POSTHOG_REMOTE_MCP_URL=${POSTHOG_REMOTE_MCP_URL:-https://mcp.posthog.com/mcp}",
        "posthog-mcp"
      ],
      "env": {
        "POSTHOG_AUTH_HEADER": "Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}",
        "POSTHOG_REMOTE_MCP_URL": "https://mcp.posthog.com/mcp"
      }
    }
  }
}

Test Docker with MCP Inspector:

pnpm docker:inspector
# or
npx @modelcontextprotocol/inspector docker run -i --rm --env POSTHOG_AUTH_HEADER=${POSTHOG_AUTH_HEADER} posthog-mcp

Environment Variables:

POSTHOG_AUTH_HEADER: Your PostHog API token (required)
POSTHOG_REMOTE_MCP_URL: The MCP server URL (optional, defaults to https://mcp.posthog.com/mcp)

This approach allows you to use the PostHog MCP server without needing Node.js or npm installed locally.

Example Prompts

What feature flags do I have active?
Add a new feature flag for our homepage redesign
What are my most common errors?
Show me my LLM costs this week

Feature Filtering

You can limit which tools are available by adding query parameters to the MCP URL:

https://mcp.posthog.com/mcp?features=flags,workspace

Available features:

workspace - Organization and project management
error-tracking - Error monitoring and debugging
dashboards - Dashboard creation and management
insights - Analytics insights and SQL queries
experiments - A/B testing experiments
flags - Feature flag management
llm-analytics - LLM usage and cost tracking
docs - PostHog documentation search

To view which tools are available per feature, see our documentation or alternatively check out schema/tool-definitions.json,

Data processing

The MCP server is hosted on a Cloudflare worker which can be located outside of the EU / US, for this reason the MCP server does not store any sensitive data outside of your cloud region.

Using self-hosted instances

If you're using a self-hosted instance of PostHog, you can specify a custom base URL by adding the POSTHOG_BASE_URL environment variable when running the MCP server locally or on your own infrastructure, e.g. POSTHOG_BASE_URL=https://posthog.example.com

Development

To run the MCP server locally, run the following command:

pnpm run dev

And replace https://mcp.posthog.com/mcp with http://localhost:8787/mcp in the MCP configuration.

Project Structure

This repository is organized to support multiple language implementations:

typescript/ - TypeScript implementation of the MCP server & tools
schema/ - Shared schema files generated from TypeScript

Development Commands

pnpm run dev - Start development server
pnpm run schema:build:json - Generate JSON schema for other language implementations
pnpm run lint && pnpm run format - Format and lint code

Adding New Tools

See the tools documentation for a guide on adding new tools to the MCP server.

Environment variables

Create .dev.vars in the root
Add Inkeep API key to enable docs-search tool (see Inkeep API key - mcp)

INKEEP_API_KEY="..."

Configuring the Model Context Protocol Inspector

During development you can directly inspect the MCP tool call results using the MCP Inspector.

You can run it using the following command:

npx @modelcontextprotocol/inspector npx -y mcp-remote@latest http://localhost:8787/mcp --header "\"Authorization: Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}\""

Alternatively, you can use the following configuration in the MCP Inspector:

Use transport type STDIO.

Command:

npx

Arguments:

-y mcp-remote@latest http://localhost:8787/mcp --header "Authorization: Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}"

{ "mcpServers": { "posthog": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.posthog.com/mcp", "--header", "Authorization:${POSTHOG_AUTH_HEADER}" ], "env": { "POSTHOG_AUTH_HEADER": "Bearer <YOUR_API_KEY>" } } } }