# Use product analytics over PostHog MCP - Docs

The [PostHog MCP server](/docs/model-context-protocol.md) gives your AI coding agent direct access to your analytics. Query trends, funnels, retention, and custom SQL, and create or update saved insights and dashboards – all from your code editor.

This works in any MCP client: Cursor, Codex, Claude Code, Windsurf, VS Code, and others.

## What you can do here

-   **Check feature performance** before making code changes – "How many users are using the new search feature this week?"
-   **Pull conversion rates** into your workflow – "What's the funnel conversion from signup to first project?"
-   **Investigate metric changes** – "Did the login success rate change after last Tuesday's deploy?"
-   **Build insights on demand** – "Create a trend showing daily active users broken down by plan."
-   **Drill into the people behind a number** – every query type has an actors variant that lists the individual persons.

## Query tools

Each insight type has its own tool, plus an actors variant that lists the persons behind a specific data point.

| Tool | Description |
| --- | --- |
| query-trends | Run a trends query and return the series. |
| query-trends-actors | List persons behind a trends data point. |
| query-funnel | Run a funnel query and return step conversion. |
| query-funnel-actors | List persons who converted through or dropped off at a step. |
| query-retention | Run a retention query and return the cohort grid. |
| query-retention-actors | List persons in a retention cohort. |
| query-paths | Run a user paths query. |
| query-paths-actors | List persons who followed a specific path. |
| query-stickiness | Run a stickiness query. |
| query-stickiness-actors | List persons at a stickiness level. |
| query-lifecycle | Run a lifecycle query. |
| query-lifecycle-actors | List persons in a lifecycle stage. |
| execute-sql | Run an arbitrary SQL query against your events and warehouse data. |
| read-data-schema | Read the available tables, columns, and event properties. |

The funnel actors tool supports two modes: **step mode**, where a positive `funnelStep` means converted and a negative one means dropped off (1-based), and **trends-dropoff mode**, using `funnelTrendsDropOff` with `funnelTrendsEntrancePeriodStart` for funnel-trends visualizations.

## Insight tools

| Tool | Description |
| --- | --- |
| insight-create | Create a saved insight from a query. |
| insight-get | Get details for a specific insight by ID. |
| insight-query | Run the query behind a saved insight and return fresh results. |
| insight-update | Update a saved insight's name, description, or query. |
| insight-delete | Delete a saved insight. |
| insights-list | List insights in the project, filtered by name or type. |
| insights-trending-retrieve | Get the insights your team looks at most. |
| insights-activity-retrieve | Get the activity log for an insight. |

## Dashboard tools

| Tool | Description |
| --- | --- |
| dashboard-create | Create a new dashboard. |
| dashboard-get | Get a dashboard and its tiles. |
| dashboards-get-all | List all dashboards in the project. |
| dashboard-update | Update a dashboard's name or description. |
| dashboard-delete | Delete a dashboard. |
| dashboard-widgets-batch-add | Add insights to a dashboard in one call. |
| dashboard-insights-run | Run every insight on a dashboard. |

## Example prompts

Try these with your MCP-enabled agent:

-   `How is the new checkout flow performing compared to last week?`
-   `Show me the top 10 events by volume today.`
-   `Create a funnel from user_signed_up to project_created to insight_viewed.`
-   `What's the retention rate for users who completed onboarding?`
-   `Run a SQL query to find the most active users by event count this month.`

## Customize chart display

When creating or updating SQL-backed insights, you can configure per-series display settings and number formatting on each Y-axis column.

**Per-series display** – set on each Y-axis column under `settings.display`:

| Setting | Values | Description |
| --- | --- | --- |
| yAxisPosition | left, right | Which Y axis the series uses. Use right for a secondary axis. |
| displayType | auto, line, bar, area | Override the chart-level display for this series. Mix types by setting different values per column. |
| trendLine | true, false | Draw a linear trend line for the series. |
| label | string | Custom label shown in the legend and tooltips instead of the column name. |
| color | hex string (e.g. #1d4aff) | Custom color for the series. |

**Number formatting** – set on each Y-axis column under `settings.formatting`:

| Setting | Values | Description |
| --- | --- | --- |
| style | none, number, short, percent | Number format style. number adds thousands separators, short abbreviates (1.2k, 3.4M). |
| prefix | string | Text prepended to values (e.g. $). |
| suffix | string | Text appended to values (e.g. % or ms). |
| decimalPlaces | number | Number of decimal places to display. |

**Chart-level settings** – set on the `DataVisualization` node:

| Setting | Values | Description |
| --- | --- | --- |
| showValuesOnSeries | true, false | Show values on each data point in the chart. |

Example prompts:

-   `Create a SQL chart of daily revenue with values formatted as dollars and a trend line.`
-   `Update insight 123 to show the conversion rate series as a line and the volume series as bars.`

## Install the MCP server

The recommended way to install is with the [AI wizard](/docs/ai-engineering/ai-wizard.md):

Terminal

PostHog AI

```bash
npx @posthog/wizard mcp add
```

The wizard supports Claude, Cursor, Windsurf, VS Code, and more. You can also [configure it manually](/docs/model-context-protocol.md#get-started-in-30-seconds).

See the [MCP server docs](/docs/model-context-protocol.md) for full setup instructions.

## Related

-   Build the same insights by hand in the [web app](/docs/product-analytics/surfaces/web-app.md).
-   Pull results into your own systems with the [API](/docs/product-analytics/surfaces/api.md).

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better