get-breakdown
Analyze website analytics by grouping data across dimensions like pages, traffic sources, countries, devices, and UTM tags to identify top-performing content and visitor patterns.
Instructions
Break down stats by a dimension (e.g. page, source, country, device, browser, OS, UTM tags). Use this for 'top pages', 'traffic sources', 'visitor countries', etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Domain of the site (e.g. 'example.com') | |
| metrics | No | Metrics to retrieve | |
| date_range | No | Time period. Use a preset like '30d' or a custom range ['2024-01-01', '2024-01-31'] | 30d |
| dimensions | Yes | Dimensions to group by. Common: 'event:page' for top pages, 'visit:source' for traffic sources, 'visit:country_name' for geography | |
| filters | No | Filters array using Plausible v2 syntax, e.g. [['is', 'event:page', ['/blog*']]] | |
| limit | No | Max number of results to return (default 10) |
Implementation Reference
- src/index.ts:238-265 (handler)The handler function for the 'get-breakdown' MCP tool, which calls the plausible-client and formats the result.
async ({ site_id, metrics, date_range, dimensions, filters, limit }) => { const result = await client.query({ site_id, metrics, date_range, dimensions, filters: filters ?? undefined, pagination: { limit }, }); // Format as rows with dimension labels + metrics const rows = result.results.map((r) => { const row: Record<string, unknown> = {}; dimensions.forEach((d, i) => { row[d] = r.dimensions[i]; }); metrics.forEach((m, i) => { row[m] = r.metrics[i]; }); return row; }); return { content: [ { type: "text", text: JSON.stringify( { site_id, date_range, dimensions, data: rows }, - src/index.ts:195-237 (registration)Registration of the 'get-breakdown' tool, including its schema definition.
server.tool( "get-breakdown", "Break down stats by a dimension (e.g. page, source, country, device, browser, OS, UTM tags). Use this for 'top pages', 'traffic sources', 'visitor countries', etc.", { site_id: z.string().describe("Domain of the site (e.g. 'example.com')"), metrics: metricsSchema, date_range: dateRangeSchema, dimensions: z .array( z.enum([ "event:page", "event:hostname", "event:goal", "visit:source", "visit:referrer", "visit:utm_source", "visit:utm_medium", "visit:utm_campaign", "visit:utm_content", "visit:utm_term", "visit:device", "visit:browser", "visit:browser_version", "visit:os", "visit:os_version", "visit:country", "visit:country_name", "visit:region", "visit:city", "visit:entry_page", "visit:exit_page", ]) ) .describe( "Dimensions to group by. Common: 'event:page' for top pages, 'visit:source' for traffic sources, 'visit:country_name' for geography" ), filters: filtersSchema, limit: z .number() .optional() .describe("Max number of results to return (default 10)") .default(10), },