runReport
Retrieve Google Analytics 4 data by specifying date ranges, dimensions, and metrics to generate custom reports for analysis.
Instructions
Run a report to get analytics data
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | Yes | Start date in YYYY-MM-DD format | |
| endDate | Yes | End date in YYYY-MM-DD format | |
| dimensions | Yes | Dimensions to group by (e.g., page, country) | |
| metrics | Yes | Metrics to include in the report | |
| dimensionFilter | No | Filter for dimensions |
Implementation Reference
- src/index.ts:269-292 (handler)Handler for the 'runReport' tool: destructures arguments, validates date range, and calls the shared fetchAnalyticsData helper with the report configuration.
case "runReport": { const { startDate, endDate, dimensions = [], metrics = [], dimensionFilter, } = args as { startDate: string; endDate: string; dimensions?: { name: string }[]; metrics?: { name: string }[]; dimensionFilter?: object; }; validateDateRange(startDate, endDate); return fetchAnalyticsData({ dateRanges: [{ startDate, endDate }], dimensions, metrics, ...(dimensionFilter && { dimensionFilter }), }); } - src/index.ts:137-175 (schema)Input schema definition for the 'runReport' tool, specifying required date ranges, dimensions, metrics, and optional filters.
type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, dimensions: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Dimensions to group by (e.g., page, country)", }, metrics: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Metrics to include in the report", }, dimensionFilter: { type: "object", description: "Filter for dimensions", }, }, required: ["startDate", "endDate", "metrics", "dimensions"], }, - src/index.ts:134-176 (registration)Tool registration object for 'runReport' returned in ListTools response, including name, description, and full input schema.
name: "runReport", description: "Run a report to get analytics data", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, dimensions: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Dimensions to group by (e.g., page, country)", }, metrics: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Metrics to include in the report", }, dimensionFilter: { type: "object", description: "Filter for dimensions", }, }, required: ["startDate", "endDate", "metrics", "dimensions"], }, }, - src/index.ts:97-127 (helper)Shared helper function that performs the actual Google Analytics Data API runReport call and formats the response as MCP content.
async function fetchAnalyticsData( reportConfig: Partial<Omit<RunReportRequest, "property">> & { dateRanges: RunReportRequest["dateRanges"]; dimensions?: RunReportRequest["dimensions"]; metrics?: RunReportRequest["metrics"]; }, ) { try { const [response] = await analyticsDataClient.runReport({ property: `properties/${propertyId}`, ...reportConfig, }); return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } catch (error) { // Handle Google Analytics API errors if (error instanceof Error) { throw new McpError( ErrorCode.InternalError, `Google Analytics API error: ${error.message}`, ); } throw new McpError(ErrorCode.InternalError, "An unexpected error occurred"); } }