runReport
Generate Google Analytics 4 reports by specifying date ranges, metrics, dimensions, and filters to analyze website performance data.
Instructions
Run a report to get analytics data
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dimensionFilter | No | Filter for dimensions | |
| dimensions | Yes | Dimensions to group by (e.g., page, country) | |
| endDate | Yes | End date in YYYY-MM-DD format | |
| metrics | Yes | Metrics to include in the report | |
| startDate | Yes | Start date in YYYY-MM-DD format |
Implementation Reference
- src/index.ts:269-292 (handler)Executes the 'runReport' tool by parsing input arguments, validating date range, and invoking fetchAnalyticsData to run the Google Analytics report.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:97-127 (handler)Core function that performs the actual Google Analytics Data API runReport call, formats the response as text content, and handles API errors.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"); } }
- src/index.ts:133-176 (registration)Registers the 'runReport' tool in the MCP server's listTools response, providing 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:47-68 (helper)Helper function to validate the startDate and endDate parameters used in the runReport tool.function validateDateRange(startDate: string, endDate: string): void { if (!validateDateFormat(startDate)) { throw new McpError( ErrorCode.InvalidParams, `Invalid startDate format. Expected YYYY-MM-DD, got: ${startDate}`, ); } if (!validateDateFormat(endDate)) { throw new McpError( ErrorCode.InvalidParams, `Invalid endDate format. Expected YYYY-MM-DD, got: ${endDate}`, ); } if (new Date(startDate) > new Date(endDate)) { throw new McpError( ErrorCode.InvalidParams, "startDate cannot be after endDate", ); } }