run_realtime_report

Execute real-time reports to retrieve current active user counts and other immediate metrics from Google Analytics 4 properties for instant performance monitoring.

Instructions

リアルタイムレポートを実行し、現在のアクティブユーザー数などを取得します。

Input Schema

TableJSON Schema

Name	Required	Description
`propertyId`	No	GA4プロパティID（省略時は環境変数を使用）
`dimensions`	No	ディメンション（デフォルト: ["country", "deviceCategory"]）
`metrics`	No	メトリクス（デフォルト: ["activeUsers"]）

Implementation Reference

src/tools/basic/runRealtimeReport.ts:15-82 (handler)

The main handler function that implements the run_realtime_report tool logic. It executes a GA4 realtime report using the provided dimensions and metrics, processes the response into rows and totals.

export async function runRealtimeReport(
  input: RunRealtimeReportInput
): Promise<RealtimeReportOutput> {
  const propertyId = getPropertyId(input.propertyId);
  const property = formatPropertyPath(propertyId);

  // デフォルト値の設定
  const dimensions = input.dimensions || ["country", "deviceCategory"];
  const metrics = input.metrics || ["activeUsers"];

  // レポート実行
  const response = await executeRealtimeReport({
    property,
    dimensions: dimensions.map((name) => ({ name })),
    metrics: metrics.map((name) => ({ name })),
  });

  // 結果を整形
  const rows: ReportRow[] = [];
  const dimensionHeaders = response.dimensionHeaders || [];
  const metricHeaders = response.metricHeaders || [];

  for (const row of response.rows || []) {
    const dimensionValues: Record<string, string> = {};
    const metricValues: Record<string, number | string> = {};

    // ディメンション値を取得
    (row.dimensionValues || []).forEach((value, index) => {
      const header = dimensionHeaders[index];
      if (header?.name) {
        dimensionValues[header.name] = value.value || "";
      }
    });

    // メトリクス値を取得
    (row.metricValues || []).forEach((value, index) => {
      const header = metricHeaders[index];
      if (header?.name) {
        const rawValue = value.value || "0";
        const numValue = parseFloat(rawValue);
        metricValues[header.name] = isNaN(numValue) ? rawValue : numValue;
      }
    });

    rows.push({ dimensions: dimensionValues, metrics: metricValues });
  }

  // 合計値の取得
  let totals: Record<string, number | string> | undefined;
  if (response.totals && response.totals.length > 0) {
    totals = {};
    const totalRow = response.totals[0];
    (totalRow.metricValues || []).forEach((value, index) => {
      const header = metricHeaders[index];
      if (header?.name) {
        const rawValue = value.value || "0";
        const numValue = parseFloat(rawValue);
        totals![header.name] = isNaN(numValue) ? rawValue : numValue;
      }
    });
  }

  return {
    rows,
    rowCount: rows.length,
    totals,
  };
}

src/server.ts:162-187 (registration)

Tool registration in the tools array, defining the name, description, and input schema for listTools response.

{
  name: "run_realtime_report",
  description:
    "リアルタイムレポートを実行し、現在のアクティブユーザー数などを取得します。",
  inputSchema: {
    type: "object" as const,
    properties: {
      propertyId: {
        type: "string",
        description: "GA4プロパティID（省略時は環境変数を使用）",
      },
      dimensions: {
        type: "array",
        items: { type: "string" },
        description:
          'ディメンション（デフォルト: ["country", "deviceCategory"]）',
      },
      metrics: {
        type: "array",
        items: { type: "string" },
        description: 'メトリクス（デフォルト: ["activeUsers"]）',
      },
    },
    required: [],
  },
},

src/server.ts:607-612 (registration)

Tool dispatcher in handleToolCall switch statement that calls the runRealtimeReport handler with parsed arguments.

case "run_realtime_report":
  return await runRealtimeReport({
    propertyId: args.propertyId as string | undefined,
    dimensions: args.dimensions as string[] | undefined,
    metrics: args.metrics as string[] | undefined,
  });

src/types.ts:83-93 (schema)

TypeScript interfaces defining the input (RunRealtimeReportInput) and output (RealtimeReportOutput) types for the tool.

// run_realtime_report
export interface RunRealtimeReportInput extends PropertyId {
  dimensions?: string[];
  metrics?: string[];
}

export interface RealtimeReportOutput {
  rows: ReportRow[];
  rowCount: number;
  totals?: Record<string, number | string>;
}

src/tools/basic/index.ts:4-4 (helper)
Re-export of the runRealtimeReport function for convenient import in server.ts.
```
export { runRealtimeReport } from "./runRealtimeReport.js";
```

GA4 MCP Server