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

# Use the data warehouse over PostHog MCP

The [PostHog MCP server](/docs/model-context-protocol.md) lets your AI coding agent run [HogQL](/docs/data-warehouse/sql.md) queries, manage [data warehouse](/docs/data-warehouse.md) views, sync import sources, annotate tables and columns, and explore your schema directly from your code editor. Query events, create and materialize views, configure Postgres/Stripe/HubSpot imports, add semantic descriptions to your data, and work with warehouse tables – without switching to the PostHog app.

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

## Before you start

1.  **Set up the Data Warehouse** – [link a source](/docs/data-warehouse/start-here.md) so there are tables to query.
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

With MCP, your coding agent can:

-   **Run ad-hoc queries** – "How many `purchase_completed` events happened this week?" to quickly check data
-   **Explore your schema** – "What tables do I have?" or "Show me the columns in `stripe_charges`" to discover available data
-   **Generate queries from questions** – "Write a HogQL query to find the top users by event count" to get a query you can refine
-   **Query across sources** – Join PostHog events with Stripe, HubSpot, or any linked warehouse table
-   **Manage views** – Create, update, materialize, and delete saved views in your data warehouse programmatically
-   **Manage import sources** – Create, configure, and sync data warehouse sources like Postgres, Stripe, and HubSpot
-   **Annotate tables and columns** – Add semantic descriptions to views and warehouse tables so PostHog AI understands your data

## SQL tools

The MCP server provides these tools for running SQL:

| Tool | Description |
| --- | --- |
| `query-run` | Run a HogQL query and return results. Supports any valid HogQL syntax including joins, CTEs, subqueries, and window functions. |
| `query-generate-hogql-from-question` | Generate a HogQL query from a natural language question. Returns the query string so you can review or modify it before running. Requires [AI data processing approval](/docs/posthog-ai/allow-access.md). |
| `property-definitions` | List all event and person properties in your project. Useful for understanding what data is available before writing a query. |
| `event-definitions-list` | List all event definitions in your project with volume and usage data. |

## View management tools

The MCP server also provides tools for managing [data warehouse views](/docs/data-warehouse/views.md):

| Tool | Description |
| --- | --- |
| `view-list` | List all saved views in your project with their materialization status, sync frequency, column schema, and descriptions. |
| `view-get` | Get full details of a specific view by ID, including its HogQL query, run history, and descriptions. |
| `view-create` | Create a new view from a HogQL query with an optional description. Upserts by name if a view with the same name exists. |
| `view-update` | Update a view's name, HogQL query, sync frequency, or description. |
| `view-delete` | Delete a view (soft delete). |
| `view-materialize` | Enable materialization for a view with a 24-hour refresh schedule. |
| `view-unmaterialize` | Revert a materialized view back to a virtual query. |
| `view-run` | Trigger a manual refresh of a materialized view. |
| `view-run-history` | Get the last 5 materialization run statuses for a view. |

## Source management tools

These tools manage [data warehouse](/docs/data-warehouse.md) import sources – external databases and services that sync data into PostHog:

| Tool | Description |
| --- | --- |
| `external-data-sources-list` | List all configured import sources in the project with connection status and sync details. |
| `external-data-sources-retrieve` | Get a single source by ID with full details including all table schemas. |
| `external-data-sources-create` | Create a new source connection. Use `external-data-sources-wizard` first to discover available source types and required fields. |
| `external-data-sources-partial-update` | Update a source's prefix, description, or connection credentials. |
| `external-data-sources-destroy` | Delete a source and all its synced data. This can't be undone. |
| `external-data-sources-reload` | Trigger a sync for all enabled tables in a source. |
| `external-data-sources-refresh-schemas` | Fetch the latest table list from the remote database and add any new tables. |
| `external-data-sources-wizard` | Get configuration metadata for all supported source types (required fields, OAuth flows, etc.). |

## Schema management tools

These tools manage individual table schemas within a data warehouse source:

| Tool | Description |
| --- | --- |
| `external-data-schemas-list` | List all table schemas across all sources with sync status and configuration. |
| `external-data-schemas-retrieve` | Get a single table schema by ID with full sync details. |
| `external-data-schemas-partial-update` | Update a table's sync type, frequency, incremental field, or enable/disable syncing. |
| `external-data-schemas-reload` | Trigger a sync for a single table using its configured sync method. |
| `external-data-schemas-resync` | Discard all synced data and re-import a table from scratch. |
| `external-data-schemas-cancel` | Cancel a currently running sync job for a table. |
| `external-data-schemas-delete-data` | Delete synced table data from PostHog but keep the schema entry for re-syncing. |

## Column annotation tools

These tools add semantic descriptions to your tables, views, and columns, helping PostHog AI understand your data:

| Tool | Description |
| --- | --- |
| `saved-query-column-annotations-create` | Add or replace a description for a view (saved query) or one of its columns. Use for views (`table_type = 'view'` in information\_schema). |
| `saved-query-column-annotations-list` | List descriptions for views and their columns. Filter by `?saved_query_id=<uuid>` to scope to one view. |
| `warehouse-column-annotations-create` | Add or replace a description for an imported warehouse table or column. Use for physical tables (`table_type = 'data_warehouse'`). |
| `warehouse-column-annotations-list` | List descriptions for warehouse tables and columns. Filter by `?table_id=<uuid>` to scope to one table. |
| `warehouse-column-annotations-partial-update` | Edit an existing warehouse table or column description by annotation ID. |

> **Note:** Core PostHog tables (events, persons, groups, sessions) cannot be annotated – they have built-in descriptions.

## Example prompts

Try these with your MCP-enabled agent:

-   `Run a HogQL query to find the top 10 events by count today.`
-   `What tables are available in my data warehouse?`
-   `Write a query joining events with stripe_subscriptions to find revenue per user.`
-   `Generate a HogQL query to calculate weekly active users by cohort.`
-   `Show me 5 sample rows from the hubspot_contacts table.`
-   `What properties are available on the purchase_completed event?`

For schema discovery:

-   `Query system.information_schema.tables to list all available tables with their descriptions.`
-   `What columns does the events table have? Use system.information_schema.columns.`
-   `Show me all relationships from the events table using system.information_schema.relationships.`
-   `List all HogQL data types from system.information_schema.data_types.`

For querying alerts:

-   `Query system.alerts to find all enabled alerts in the project.`
-   `Show me alerts that check hourly and their last check results.`
-   `Write a HogQL query to find alerts that fired in the last week.`

For schema discovery using [`system.information_schema`](/docs/data-warehouse/sources/posthog.md#schema-discovery-with-information_schema):

-   `Query system.information_schema.columns to find all columns in the events table with their types and descriptions.`
-   `Use system.information_schema.relationships to show me how the events table joins to other tables.`
-   `Search system.information_schema.tables for any table related to subscriptions.`

For view management:

-   `List all my saved views in the data warehouse.`
-   `Create a view called 'daily_active_users' that counts distinct user_ids per day.`
-   `Materialize my 'revenue_summary' view for faster queries.`
-   `Trigger a refresh of my 'user_metrics' materialized view.`
-   `Show me the run history for my 'sales_data' view.`
-   `Set the description for my 'daily_active_users' view to explain what it calculates.`

For source management:

-   `List all my data warehouse sources.`
-   `What tables are available in my Stripe source?`
-   `Trigger a sync for my Postgres source.`
-   `Show me the sync status for all my import schemas.`
-   `Cancel the running sync on the hubspot_contacts table.`

For column annotations:

-   `Add a description to my 'revenue_summary' view explaining it calculates monthly recurring revenue.`
-   `Describe the 'amount' column in my stripe_charges table as 'Transaction amount in cents'.`
-   `List all column descriptions for my user_metrics view.`
-   `What descriptions exist for my imported Stripe tables?`

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

-   [Use the data warehouse in the web app](/docs/data-warehouse/surfaces/web-app.md) for the SQL editor, source setup, and insights.
-   [Use the data warehouse over the API](/docs/data-warehouse/surfaces/api.md) for the same operations from your own scripts.
-   [Use the data warehouse in PostHog Desktop](/docs/data-warehouse/surfaces/desktop.md) to work through failing models and syncs.
-   [Manage data quality over MCP and SQL](/docs/data-warehouse/data-quality/mcp.md) to create checks, start runs, and inspect results.
-   [Views](/docs/data-warehouse/views.md) and [materialized views](/docs/data-warehouse/views/materialize.md) for what the view tools manage.
-   [Sources](/docs/data-warehouse/sources.md) for what the source and schema tools configure.

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better