> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Use product analytics over PostHog MCP

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.

## Before you start

1.  **Set up Product Analytics** – [install a PostHog SDK](/docs/product-analytics/installation.md) so events are captured.
2.  **Connect the MCP server** – [install it in your AI tool](#install-the-mcp-server) and give it access to your project.

## 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

```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).

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better