Posthog Mcp

What is Posthog Mcp about?

Posthog Mcp offers a ready‑to‑use MCP server that bridges PostHog’s product‑analytics ecosystem with AI models. By exposing tools such as feature‑flag management, error monitoring, dashboard queries, experiment results, LLM cost tracking, and docs search, it enables conversational assistants to retrieve and act on real‑time product data.

How to use Posthog Mcp?

Quick install (recommended)

npx @posthog/wizard@latest mcp add

The wizard adds the necessary MCP configuration to supported desktop clients (Cursor, Claude, VS Code, Zed, etc.).

Manual install

Add the following JSON to your client’s mcpServers configuration, replacing {INSERT_YOUR_PERSONAL_API_KEY_HERE} with a personal API key obtained from PostHog:

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

Docker install

# Build the image
pnpm docker:build   # or: docker build -t posthog-mcp .

# Run via MCP client configuration
{
  "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 the Docker image with the MCP Inspector:

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

Key features of Posthog Mcp

• Workspace management – organization and project handling.
• Error‑tracking – view and debug recent errors.
• Dashboard tooling – list, create, and modify dashboards.
• Insights & SQL – run product‑analytics queries.
• Experiments – access A/B test results.
• Feature flags – enumerate, add, or modify flags.
• LLM analytics – monitor LLM usage and cost data.
• Docs search – full‑text search of PostHog documentation.
• Feature filtering – limit exposed tools via query parameters, e.g. ?features=flags,workspace.
• Self‑hosted support – set POSTHOG_BASE_URL to point to a private PostHog instance.
• Environment variables – POSTHOG_AUTH_HEADER (required) and optional POSTHOG_REMOTE_MCP_URL.

Use cases of Posthog Mcp

• AI‑driven product support – an assistant can answer “What feature flags are active for the homepage?”
• Operational alerts – retrieve the most common errors without leaving the chat UI.
• Cost monitoring – ask “Show me my LLM costs this week” and get a breakdown.
• Rapid experimentation – query experiment results on‑the‑fly while discussing product decisions.
• Documentation lookup – search PostHog docs directly from the chat interface.
• Custom tooling – developers can script automated flag toggles or dashboard updates via the MCP endpoint.

FAQ from the Posthog Mcp

Q: Do I need Node.js installed locally? A: No. The quick‑install command uses npx, which downloads the package on‑the‑fly. Docker is also supported for completely node‑free environments.

Q: How do I obtain an API key? A: Generate a personal API key from PostHog → Settings → User API keys, selecting the MCP Server preset.

Q: Can I run the server on my own infrastructure? A: Yes. Set POSTHOG_BASE_URL to your self‑hosted PostHog URL when starting the server (via Cloudflare Workers or Docker). The server will route requests to that instance.

Q: Which tools are available by default? A: All listed under Key features are enabled. You can restrict them with the features query parameter in the MCP URL.

Q: What if I only want feature‑flag management? A: Use https://mcp.posthog.com/mcp?features=flags (or add additional comma‑separated features as needed).

Q: Is any sensitive data stored outside my region? A: The MCP server runs on a Cloudflare worker and does not persist sensitive data; it only proxies requests to your PostHog instance.

Q: How do I add new tools? A: Follow the guidance in typescript/src/tools/README.md and regenerate the shared schema with pnpm run schema:build:json.

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

1. Obtain a personal API key using the MCP Server preset here.

2. 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:

1. Build the Docker image:

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

2. 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"
      }
    }
  }
}

3. 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}"