mcp-server-google-analytics

Instructions

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");
    }
  }