GA4 MCP Server

Instructions

Implementation Reference

• src/tools/analytics/getTopPages.ts:10-67 (handler)

  Main handler function implementing the get_top_pages tool logic. Fetches GA4 report data for top pages by page views, processes dimensions and metrics, formats results into TopPage objects ranked by page views.

  export async function getTopPages(
    input: GetTopPagesInput
  ): Promise<GetTopPagesOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
    const limit = input.limit || 10;
  
    const response = await executeReport({
      property,
      dateRanges: [dateRange],
      dimensions: [{ name: "pagePath" }, { name: "pageTitle" }],
      metrics: [
        { name: "screenPageViews" },
        { name: "totalUsers" },
        { name: "averageSessionDuration" },
        { name: "bounceRate" },
      ],
      orderBys: [{ metric: { metricName: "screenPageViews" }, desc: true }],
      limit,
      ...(input.pathFilter && {
        dimensionFilter: {
          filter: {
            fieldName: "pagePath",
            stringFilter: {
              matchType: "BEGINS_WITH",
              value: input.pathFilter,
            },
          },
        },
      }),
    });
  
    const pages: TopPage[] = [];
    let rank = 1;
  
    for (const row of response.rows || []) {
      const dimensionValues = row.dimensionValues || [];
      const metricValues = row.metricValues || [];
  
      const getValue = (index: number): number => {
        const value = metricValues[index]?.value;
        return value ? parseFloat(value) : 0;
      };
  
      pages.push({
        rank: rank++,
        pagePath: dimensionValues[0]?.value || "",
        pageTitle: dimensionValues[1]?.value || "(タイトルなし)",
        pageViews: Math.round(getValue(0)),
        uniquePageViews: Math.round(getValue(1)),
        avgTimeOnPage: formatDuration(getValue(2)),
        bounceRate: formatPercentageFromDecimal(getValue(3)),
      });
    }
  
    return { pages };
  }

• src/types.ts:131-149 (schema)

  TypeScript interfaces defining input (GetTopPagesInput), output (GetTopPagesOutput), and data structure (TopPage) for the get_top_pages tool.

  export interface GetTopPagesInput extends PropertyId {
    period: ShortPeriod;
    limit?: number;
    pathFilter?: string;
  }
  
  export interface TopPage {
    rank: number;
    pagePath: string;
    pageTitle: string;
    pageViews: number;
    uniquePageViews: number;
    avgTimeOnPage: string;
    bounceRate: string;
  }
  
  export interface GetTopPagesOutput {
    pages: TopPage[];
  }

• src/server.ts:221-246 (registration)

  MCP tool registration in the tools array, defining name, description, and inputSchema for get_top_pages.

  {
    name: "get_top_pages",
    description:
      "人気ページのランキングを取得します。PV数、滞在時間、直帰率などを確認できます。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["today", "yesterday", "7days", "28days", "30days"],
          description: "集計期間",
        },
        limit: {
          type: "number",
          description: "取得件数（デフォルト: 10）",
        },
        pathFilter: {
          type: "string",
          description:
            'パスのフィルター（例: "/blog" で /blog 配下のみを取得）',
        },
      },
      required: ["period"],
    },
  },

• src/server.ts:632-643 (registration)

  Dispatch handler in switch statement that calls the getTopPages function with parsed arguments.

  case "get_top_pages":
    return await getTopPages({
      propertyId: args.propertyId as string | undefined,
      period: args.period as
        | "today"
        | "yesterday"
        | "7days"
        | "28days"
        | "30days",
      limit: args.limit as number | undefined,
      pathFilter: args.pathFilter as string | undefined,
    });

• src/tools/analytics/index.ts:2-2 (helper)

  Re-export of the getTopPages handler from its implementation file for convenient import in server.ts.

  export { getTopPages } from "./getTopPages.js";