Model Context Protocol (MCP)

The PostHog Model Context Protocol (MCP) server enables your AI agents and tools to directly interact with PostHog's products.

Quick install using the PostHog wizard

Besides being able to quickly set up your project using AI, the PostHog Wizard can also install the MCP server directly into Cursor, Claude Code, Claude Desktop, Codex, VS Code and Zed.

npx @posthog/wizard mcp add

We're working on adding more supported tools to the wizard. If you're using another option, you can manually install our MCP server with the instructions below.

Manual install

Add the MCP configuration to your client. When you first use the MCP server, you'll be prompted to log in to PostHog to authenticate.

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

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.posthog.com/sse"
      ]
    }
  }
}

codex mcp add posthog --url https://mcp.posthog.com/mcp

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.posthog.com/sse"
      ]
    }
  }
}

{
  "servers": {
    "posthog": {
      "type": "http",
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

{
  "context_servers": {
    "posthog": {
      "enabled": true,
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

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

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp",
      "headers": {
        "Authorization": "Bearer phx_your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp",
      "headers": {
        "Authorization": "Bearer phx_your_api_key_here",
        "x-posthog-organization-id": "your_org_id",
        "x-posthog-project-id": "your_project_id"
      }
    }
  }
}

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp",
      "headers": {
        "Authorization": "Bearer phx_your_api_key_here",
        "x-posthog-readonly": "true"
      }
    }
  }
}

Available Tools

Tools trigger actions on behalf of the user based on the goals and information already in the context of the LLM.

Here's a list of tools we provide:

Example prompts

Here are some examples of what you can ask your AI agent to do with the PostHog MCP server:

Feature flag management

Prompt: "Create a feature flag called 'new-checkout-flow' that's enabled for 20% of users"

The agent will use the create-feature-flag tool to create the flag with a 20% rollout and return the configuration including the key, rollout percentage, and a link to the flag in PostHog.

Multivariate feature flags

Prompt: "Create a multivariate feature flag called 'homepage-hero-test' with three variants: control at 34%, variant_a at 33%, and variant_b at 33%"

The agent will use the create-feature-flag tool with a multivariate configuration to create the flag with multiple variants. Variant rollout percentages must be integers that sum to 100.

Analytics queries

Prompt: "How many unique users signed up in the last 7 days, broken down by day?"

The agent will use the query-run tool to execute a trends query and return daily signup counts.

Path analysis

Prompt: "What are the most common paths users take after signing up?"

The agent will use the query-run tool with a PathsQuery to analyze user journeys, returning the flow of events users follow after signup.

Prompt: "Show me the navigation paths from the pricing page to checkout"

The agent will execute a paths query with startPoint set to the pricing page and endPoint set to checkout, revealing the most common routes users take.

SQL and HogQL queries

Your AI agent can execute complex HogQL queries to analyze both system data and analytics data in PostHog.

Prompt: "Query my feature flags to find all flags that are rolled out to less than 50% of users"

The agent will use SQL to query the system.feature_flags table and return flags filtered by rollout percentage.

Prompt: "Write a HogQL query to find users who triggered the signup event but didn't complete onboarding in the last 30 days"

The agent will construct and execute a HogQL query against the events table, using subqueries to find users who signed up but are missing the onboarding completion event.

Prompt: "What cohorts contain users who made a purchase in the last week?"

The agent will query system.cohorts and cross-reference with purchase events to identify relevant cohorts.

A/B test creation

Prompt: "Create an A/B test for our pricing page that measures conversion to checkout"

The agent will use experiment-create to set up an experiment with control/test variants and configure a funnel metric measuring pricing page to checkout conversion.

Error investigation

Prompt: "What are the top 5 errors in my project this week?"

The agent will use the list-errors tool to fetch error groups sorted by occurrence count and return details including affected user counts.

Log investigation

Prompt: "Show me error logs from the payments service in the last hour"

The agent will use logs-query to search for logs filtered by severity level and service name, returning log entries with timestamps, messages, and trace information.

Prompt management

Prompt: "List all prompts stored in my project"

The agent will use the prompt-list tool to retrieve all team prompts and return a summary with names, versions, and timestamps.

Prompt: "Create a prompt called 'code-reviewer' with instructions for reviewing pull requests"

The agent will use the prompt-create tool to create a new prompt with the specified name and content, making it available for use across all MCP-connected agents in your team.

Prompt: "Get the latest version of my 'support-assistant' prompt"

The agent will use the prompt-get tool to retrieve the full prompt content by name. You can also request a specific version if needed.

Prompt: "Update the 'onboarding-guide' prompt to include a section about feature flags"

The agent will use the prompt-update tool to publish a new version of the prompt with the updated content. The update includes conflict detection to prevent overwriting changes made by others.

Annotation management

Prompt: "Create an annotation for today saying 'Deployed v2.5 with new checkout flow'"

The agent will use the annotation-create tool to create an annotation with the content and date, scoped to your current project. Annotations appear on charts to mark deployments, releases, and other significant changes.

Prompt: "List all annotations from the last month"

The agent will use the annotations-list tool to retrieve annotations, letting you review existing markers on your charts and dashboards.

Prompt: "Add an organization-wide annotation for March 15th marking our company rebrand"

The agent will create an annotation with scope set to organization so it appears across all projects in your organization.

Activity log queries

Prompt: "Show me all recent feature flag changes in the project"

The agent will use the activity-logs-list tool with scope set to FeatureFlag to return recent activity logs showing who created, updated, or deleted feature flags, including the specific fields that changed.

Prompt: "Who made changes to dashboard 42?"

The agent will use the activity-logs-list tool with scope set to Dashboard and item_id set to 42 to return all modifications to that specific dashboard, including who made each change and when.

Prompt: "What has changed in the project recently?"

The agent will use the activity-logs-list tool to return all recent activity across the project, ordered by most recent first, including feature flag updates, insight creations, experiment launches, and other changes.

Alert management

Prompt: "Create a daily alert on my pageview insight that fires when the value exceeds 500"

The agent will use the alert-create tool to create an alert with an absolute threshold. It will set up the alert to monitor the specified insight and notify subscribed users when the threshold is breached.

Prompt: "List all my alerts and show their current state"

The agent will use the alerts-list tool to retrieve all alerts in the project, returning their names, thresholds, current state (firing or not), and check intervals.

Prompt: "Update my pageview alert to fire when the value increases by more than 50% compared to the previous period"

The agent will use the alert-update tool to change the alert condition to a relative increase with a percentage threshold.

Prompt: "Snooze my pageview alert for 2 hours"

The agent will use the alert-update tool to set snoozed_until to temporarily pause notifications.

Prompt: "Delete the old weekly report alert"

The agent will use the alerts-list tool to find the alert by name, then use alert-delete to permanently remove it.

Notebook management

Prompt: "List all notebooks in my project"

The agent will use the notebooks-list tool to retrieve all notebooks and return a summary including titles, short IDs, and creation dates.

Prompt: "Create a new notebook called 'Q1 Analysis' with some initial content"

The agent will use the notebooks-create tool to create a notebook with the specified title and content as a ProseMirror-based JSON document structure.

Prompt: "Update the notebook 'abc123' to add a new section about user retention"

The agent will first use notebooks-retrieve to get the current content and version, then use notebooks-partial-update with the updated content and the correct version number for concurrency control.

Prompt: "Delete the notebook with ID 'xyz789'"

The agent will use the notebooks-destroy tool to soft-delete the notebook by its short_id.

Person management

Prompt: "Find all persons with email containing 'alice@example.com'"

The agent will use the persons-list tool with the email parameter to search for matching persons, returning their properties, distinct IDs, and a link to view them in PostHog.

Prompt: "Get the details for person ID 42 and show me which cohorts they belong to"

The agent will first use persons-retrieve to get the person's full profile, then use persons-cohorts-retrieve to list all cohorts the person is a member of.

Prompt: "Set the 'plan' property to 'enterprise' on the person with distinct_id 'user_abc123'"

The agent will use persons-list to find the person by distinct_id, then use persons-property-set to update their plan property. This is an async operation – the change is queued and processed by PostHog.

Prompt: "Remove the 'legacy_flag' property from person ID 42"

The agent will use persons-property-delete to remove the specified property from the person.

Prompts and resources

The MCP server provides resources, including framework-specific documentation and example code, to help agents build great PostHog integrations. You can try these yourself using the posthog:posthog-setup prompt, available via a slash command in your agent. Just hit the / key.

Currently we support Next.js, with more frameworks in progress.

Privacy and support

• Privacy Policy: posthog.com/privacy
• Terms of Service: posthog.com/terms
• Support: posthog.com/questions or in-app support

The MCP server acts as a proxy to your PostHog instance. It does not store your analytics data - all queries are executed against your PostHog project and results are returned directly to your AI client.

Next steps

• Lovable integration: Set up PostHog in your Lovable project
• Replit integration: Set up PostHog with Replit Agent
• v0 integration: Set up PostHog with v0 and the Vercel Flags SDK
• PostHog MCP server: Check out GitHub repository for the MCP server
• Model Context Protocol: Learn more about the Model Context Protocol specification
• MCP: machine/copy paste: What exactly is MCP again?