Model context protocol (MCP)

Last updated:

|Edit this page|

On this page

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 and Claude Desktop.

Terminal
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

Start by getting a personal API key using the MCP Server preset here.

This lets you add the MCP configuration to any desktop client you use, such as Cursor, Windsurf, or Claude Desktop.

Don't forget to use your personal API key

In all examples, make sure to replace the highlighted POSTHOG_AUTH_HEADER environment variable placeholder with the personal API key you obtained in the first step.

Run the following command in your shell. The next time you run Claude Code, it will have access to the PostHog MCP.

Terminal
claude mcp add-json posthog -s user '{
  "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} "
  }
}'
Security considerations

We recommend the following best practices to mitigate security risks when using the PostHog MCP server:

  • Use the right API key permissions: Use the provided MCP Server preset in the personal API key creator. If you use the MCP in an agentic workflow on production data, scope down the API key's permissions to only the permissions you want it to use. This prevents the AI from making unintended changes to your PostHog configuration or data.

  • Project scoping: Scope your MCP server to a specific PostHog project, limiting access to only that project's resources. This prevents AI agents from accessing data from other projects in your PostHog account and helps maintain data isolation.

  • Be mindful of prompt injection: Keep in mind that LLMs can be tricked into following untrusted commands within user content. Always review and sanitize tool calls before executing them.

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:

Organization & project management

ToolPurpose
organizations-getGet the organizations the user has access to.
switch-organizationChange the active organization from the default organization.
organization-details-getGet the details of the active organization.
projects-getFetches projects that the user has access to in the current organization.
switch-projectChange the active project from the default project.
property-definitionsGet event and property definitions for the project.

Feature flags

ToolPurpose
feature-flag-get-allGet all feature flags in the project.
feature-flag-get-definitionGet the definition of a feature flag.
create-feature-flagCreates a new feature flag in the project.
update-feature-flagUpdate a feature flag in the project.
delete-feature-flagDelete a feature flag in the project.

Insights & analytics

ToolPurpose
insights-get-allGet all insights in the project with optional filtering.
insight-getGet a specific insight by ID.
insight-create-from-querySave a query as an insight.
insight-updateUpdate an existing insight by ID.
insight-deleteDelete an insight by ID.
insight-queryExecute a query on an existing insight to get its results/data.
get-sql-insightQueries project's PostHog data based on a provided natural language question.

Dashboards

ToolPurpose
dashboards-get-allGet all dashboards in the project with optional filtering.
dashboard-getGet a specific dashboard by ID.
dashboard-createCreate a new dashboard in the project.
dashboard-updateUpdate an existing dashboard by ID.
dashboard-deleteDelete a dashboard by ID.
add-insight-to-dashboardAdd an existing insight to a dashboard.

Error tracking

ToolPurpose
list-errorsList errors in the project.
error-detailsGet the details of an error in the project.

Documentation

ToolPurpose
docs-searchSearch the PostHog documentation for information.

LLM observability

ToolPurpose
get-llm-total-costs-for-projectFetches the total LLM daily costs for each model for a project over a given number of days.

Next Steps

Questions? Ask Max AI.

It's easier than reading through 717 pages of documentation

Community questions

Was this page useful?

Next article

Hog

We want you to have the power to transform and export your data in real time, without the headache of maintaining your own service to get it done. Enter Hog: the language that drives our realtime destinations . We’ve written Hog destination templates for dozens of services. But you can also write destinations yourself. Here’s how it works. Note: Hog shouldn't be confused with HogQL, the former name of our SQL-like query language used inside PostHog. If you're looking to query data in PostHog…

Read next article