GA4 MCP Server

Instructions

Implementation Reference

• src/tools/analytics/getUserJourney.ts:16-86 (handler)

  The primary handler function implementing the get_user_journey tool. It analyzes pages viewed in the same session as the target page using GA4 reports.

  export async function getUserJourney(
    input: GetUserJourneyInput
  ): Promise<GetUserJourneyOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
    const limit = input.limit || 10;
  
    // GA4では直接的なページ遷移情報が取得しにくいため、
    // 対象ページと同じセッションで閲覧されたページを分析
    // より正確な分析にはBigQuery Export が必要
  
    // 対象ページにアクセスしたセッション数を取得
    const targetResponse = await executeReport({
      property,
      dateRanges: [dateRange],
      dimensions: [{ name: "pagePath" }],
      metrics: [{ name: "sessions" }],
      dimensionFilter: {
        filter: {
          fieldName: "pagePath",
          stringFilter: {
            matchType: "EXACT",
            value: input.pagePath,
          },
        },
      },
    });
  
    const targetSessions =
      targetResponse.totals?.[0]?.metricValues?.[0]?.value
        ? Math.round(parseFloat(targetResponse.totals[0].metricValues[0].value))
        : 0;
  
    // 全ページのアクセス状況を取得
    const allPagesResponse = await executeReport({
      property,
      dateRanges: [dateRange],
      dimensions: [{ name: "pagePath" }],
      metrics: [{ name: "sessions" }],
      orderBys: [{ metric: { metricName: "sessions" }, desc: true }],
      limit: limit + 1, // 対象ページ自体を除外するため+1
    });
  
    const relatedPages: RelatedPage[] = [];
  
    for (const row of allPagesResponse.rows || []) {
      const pagePath = row.dimensionValues?.[0]?.value || "";
      
      // 対象ページ自体は除外
      if (pagePath === input.pagePath) continue;
      
      const count = row.metricValues?.[0]?.value
        ? Math.round(parseFloat(row.metricValues[0].value))
        : 0;
  
      relatedPages.push({
        pagePath,
        count,
        percentage: calculatePercentage(count, targetSessions),
      });
  
      if (relatedPages.length >= limit) break;
    }
  
    return {
      targetPage: input.pagePath,
      direction: input.direction,
      relatedPages,
    };
  }

• src/types.ts:287-305 (schema)

  TypeScript interfaces defining the input (GetUserJourneyInput), supporting types (RelatedPage), and output (GetUserJourneyOutput) for the tool.

  // get_user_journey
  export interface GetUserJourneyInput extends PropertyId {
    period: ShortPeriod;
    pagePath: string;
    direction: "next" | "previous";
    limit?: number;
  }
  
  export interface RelatedPage {
    pagePath: string;
    count: number;
    percentage: string;
  }
  
  export interface GetUserJourneyOutput {
    targetPage: string;
    direction: "next" | "previous";
    relatedPages: RelatedPage[];
  }

• src/server.ts:398-427 (registration)

  MCP tool registration defining the name, description, and input schema for get_user_journey.

  {
    name: "get_user_journey",
    description:
      "特定ページの前後に閲覧されるページを分析します。ユーザーの回遊パターンの把握に便利です。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["7days", "28days", "30days"],
          description: "集計期間",
        },
        pagePath: {
          type: "string",
          description: '分析対象のページパス（例: "/product/123"）',
        },
        direction: {
          type: "string",
          enum: ["next", "previous"],
          description: "next: 次に見たページ、previous: 前に見たページ",
        },
        limit: {
          type: "number",
          description: "取得件数（デフォルト: 10）",
        },
      },
      required: ["period", "pagePath", "direction"],
    },
  },

• src/server.ts:702-709 (registration)

  Dispatch handler in the switch statement that calls the getUserJourney function when the tool is invoked.

  case "get_user_journey":
    return await getUserJourney({
      propertyId: args.propertyId as string | undefined,
      period: args.period as "7days" | "28days" | "30days",
      pagePath: args.pagePath as string,
      direction: args.direction as "next" | "previous",
      limit: args.limit as number | undefined,
    });