GA4 MCP Server

Instructions

Implementation Reference

• src/tools/analytics/getGeoBreakdown.ts:13-61 (handler)

  The main asynchronous handler function that implements the core logic for the get_geo_breakdown tool, querying GA4 for geographic breakdown data by country or city.

  export async function getGeoBreakdown(
    input: GetGeoBreakdownInput
  ): Promise<GetGeoBreakdownOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
    const limit = input.limit || 10;
  
    // level に応じてディメンションを選択
    const dimension = input.level === "city" ? "city" : "country";
  
    const response = await executeReport({
      property,
      dateRanges: [dateRange],
      dimensions: [{ name: dimension }],
      metrics: [{ name: "totalUsers" }, { name: "sessions" }],
      orderBys: [{ metric: { metricName: "totalUsers" }, desc: true }],
      limit,
    });
  
    // 合計ユーザー数を取得
    const totalUsers =
      response.totals?.[0]?.metricValues?.[0]?.value
        ? parseFloat(response.totals[0].metricValues[0].value)
        : 0;
  
    const locations: LocationData[] = [];
  
    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;
      };
  
      const users = Math.round(getValue(0));
  
      locations.push({
        name: dimensionValues[0]?.value || "(不明)",
        users,
        sessions: Math.round(getValue(1)),
        percentage: calculatePercentage(users, totalUsers),
      });
    }
  
    return { locations };
  }

• src/types.ts:204-220 (schema)

  TypeScript interfaces defining the input (GetGeoBreakdownInput), supporting types (LocationData), and output (GetGeoBreakdownOutput) for the get_geo_breakdown tool.

  // get_geo_breakdown
  export interface GetGeoBreakdownInput extends PropertyId {
    period: ShortPeriod;
    level: "country" | "city";
    limit?: number;
  }
  
  export interface LocationData {
    name: string;
    users: number;
    sessions: number;
    percentage: string;
  }
  
  export interface GetGeoBreakdownOutput {
    locations: LocationData[];
  }

• src/server.ts:286-310 (registration)

  Registration of the get_geo_breakdown tool in the tools array, defining its name, description, and input schema for MCP.

  {
    name: "get_geo_breakdown",
    description: "地域別（国または市区町村）のアクセス分析結果を取得します。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["7days", "28days", "30days"],
          description: "集計期間",
        },
        level: {
          type: "string",
          enum: ["country", "city"],
          description: "地域レベル",
        },
        limit: {
          type: "number",
          description: "取得件数（デフォルト: 10）",
        },
      },
      required: ["period", "level"],
    },
  },

• src/server.ts:663-669 (registration)

  Dispatch handler in the switch statement within handleToolCall that routes calls to the get_geo_breakdown tool to its implementation.

  case "get_geo_breakdown":
    return await getGeoBreakdown({
      propertyId: args.propertyId as string | undefined,
      period: args.period as "7days" | "28days" | "30days",
      level: args.level as "country" | "city",
      limit: args.limit as number | undefined,
    });

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

  Re-export of the getGeoBreakdown handler from its module, allowing it to be imported in server.ts.

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