GA4 MCP Server

Instructions

Implementation Reference

• src/tools/analytics/getEngagementMetrics.ts:13-67 (handler)

  The core async handler function that executes the tool logic: fetches GA4 report data for engagement metrics like engagementRate, userEngagementDuration, etc., computes derived metrics, and formats the output.

  export async function getEngagementMetrics(
    input: GetEngagementMetricsInput
  ): Promise<GetEngagementMetricsOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
  
    const response = await executeReport({
      property,
      dateRanges: [dateRange],
      metrics: [
        { name: "engagementRate" },
        { name: "userEngagementDuration" },
        { name: "engagedSessions" },
        { name: "totalUsers" },
        { name: "eventCount" },
        { name: "sessions" },
      ],
    });
  
    const metricValues = response.totals?.[0]?.metricValues || [];
    const getValue = (index: number): number => {
      const value = metricValues[index]?.value;
      return value ? parseFloat(value) : 0;
    };
  
    const engagementRate = getValue(0);
    const userEngagementDuration = getValue(1);
    const engagedSessions = getValue(2);
    const totalUsers = getValue(3);
    const eventCount = getValue(4);
    const sessions = getValue(5);
  
    // エンゲージセッション/ユーザー
    const engagedSessionsPerUser =
      totalUsers > 0 ? roundToDecimal(engagedSessions / totalUsers) : 0;
  
    // イベント/セッション
    const eventsPerSession =
      sessions > 0 ? roundToDecimal(eventCount / sessions) : 0;
  
    // 平均エンゲージメント時間
    const avgEngagementTime =
      totalUsers > 0
        ? formatDuration(userEngagementDuration / totalUsers)
        : "0秒";
  
    return {
      engagementRate: formatPercentageFromDecimal(engagementRate),
      avgEngagementTime,
      engagedSessionsPerUser,
      eventsPerSession,
      // スクロール深度は別途イベントベースの設定が必要なため省略
    };
  }

• src/types.ts:389-407 (schema)

  TypeScript interfaces defining the input (GetEngagementMetricsInput extending PropertyId with period) and output (GetEngagementMetricsOutput) schemas for the tool, including related ScrollDepth type.

  // get_engagement_metrics
  export interface GetEngagementMetricsInput extends PropertyId {
    period: ShortPeriod;
  }
  
  export interface ScrollDepth {
    reached25: string;
    reached50: string;
    reached75: string;
    reached100: string;
  }
  
  export interface GetEngagementMetricsOutput {
    engagementRate: string;
    avgEngagementTime: string;
    engagedSessionsPerUser: number;
    eventsPerSession: number;
    scrollDepth?: ScrollDepth;
  }

• src/server.ts:523-539 (registration)

  MCP tool registration entry in the tools array, defining name, description, and inputSchema for 'get_engagement_metrics'.

  {
    name: "get_engagement_metrics",
    description:
      "エンゲージメント関連の詳細指標（エンゲージメント率、平均エンゲージメント時間など）を取得します。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["7days", "28days", "30days"],
          description: "集計期間",
        },
      },
      required: ["period"],
    },
  },

• src/server.ts:738-742 (registration)

  Dispatch case in the handleToolCall switch statement that invokes the getEngagementMetrics handler with parsed arguments.

  case "get_engagement_metrics":
    return await getEngagementMetrics({
      propertyId: args.propertyId as string | undefined,
      period: args.period as "7days" | "28days" | "30days",
    });

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

  Re-export of the getEngagementMetrics handler from its implementation file, allowing import from the analytics index.

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