GA4 MCP Server

Instructions

Implementation Reference

• src/tools/basic/runReport.ts:13-117 (handler)

  Core handler function implementing the run_report tool logic: validates input, constructs GA4 API request, executes report, processes and formats response into structured output.
  export async function runReport(input: RunReportInput): Promise<RunReportOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); // 日付を解決 const startDate = resolveDate(input.startDate); const endDate = resolveDate(input.endDate); // リクエストオプションを構築 const options: RunReportOptions = { property, dateRanges: [{ startDate, endDate }], dimensions: input.dimensions.map((name) => ({ name })), metrics: input.metrics.map((name) => ({ name })), limit: input.limit || 10, }; // フィルターの設定 if (input.dimensionFilter) { options.dimensionFilter = { filter: { fieldName: input.dimensionFilter.fieldName, stringFilter: { matchType: input.dimensionFilter.stringFilter.matchType, value: input.dimensionFilter.stringFilter.value, caseSensitive: input.dimensionFilter.stringFilter.caseSensitive, }, }, }; } // ソートの設定 if (input.orderBy) { options.orderBys = []; if (input.orderBy.metric) { options.orderBys.push({ metric: { metricName: input.orderBy.metric }, desc: input.orderBy.desc ?? true, }); } else if (input.orderBy.dimension) { options.orderBys.push({ dimension: { dimensionName: input.orderBy.dimension }, desc: input.orderBy.desc ?? false, }); } } // レポート実行 const response = await executeReport(options); // 結果を整形 const rows: ReportRow[] = []; const dimensionHeaders = response.dimensionHeaders || []; const metricHeaders = response.metricHeaders || []; for (const row of response.rows || []) { const dimensions: Record<string, string> = {}; const metrics: Record<string, number | string> = {}; // ディメンション値を取得 (row.dimensionValues || []).forEach((value, index) => { const header = dimensionHeaders[index]; if (header?.name) { dimensions[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); metrics[header.name] = isNaN(numValue) ? rawValue : numValue; } }); rows.push({ dimensions, metrics }); } // 合計値の取得 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, metadata: { dataLossFromOtherRow: response.metadata?.dataLossFromOtherRow || false, }, }; }
• src/server.ts:87-161 (registration)

  MCP tool registration: defines name 'run_report', description, and detailed input schema for validation.
  { name: "run_report", description: "GA4の汎用レポートを実行します。任意のディメンションとメトリクスを指定して柔軟にデータを取得できます。", inputSchema: { type: "object" as const, properties: { propertyId: { type: "string", description: "GA4プロパティID（省略時は環境変数GA4_PROPERTY_IDを使用）", }, startDate: { type: "string", description: '開始日（YYYY-MM-DD形式、または "today", "yesterday", "7daysAgo" など）', }, endDate: { type: "string", description: '終了日（YYYY-MM-DD形式、または "today", "yesterday" など）', }, dimensions: { type: "array", items: { type: "string" }, description: 'ディメンション名の配列（例: ["pagePath", "deviceCategory"]）', }, metrics: { type: "array", items: { type: "string" }, description: 'メトリクス名の配列（例: ["screenPageViews", "sessions"]）', }, dimensionFilter: { type: "object", description: "ディメンションフィルター（オプション）", properties: { fieldName: { type: "string" }, stringFilter: { type: "object", properties: { matchType: { type: "string", enum: [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "REGEXP", ], }, value: { type: "string" }, caseSensitive: { type: "boolean" }, }, }, }, }, orderBy: { type: "object", description: "ソート設定（オプション）", properties: { metric: { type: "string" }, dimension: { type: "string" }, desc: { type: "boolean" }, }, }, limit: { type: "number", description: "取得件数（デフォルト: 10、最大: 100000）", }, }, required: ["startDate", "endDate", "dimensions", "metrics"], }, },
• src/types.ts:43-81 (schema)

  TypeScript type definitions for RunReportInput, RunReportOutput, and supporting types used for type safety in the handler.
  // run_report export interface DimensionFilter { fieldName: string; stringFilter: { matchType: "EXACT" | "BEGINS_WITH" | "CONTAINS" | "ENDS_WITH" | "REGEXP"; value: string; caseSensitive?: boolean; }; } export interface OrderBy { metric?: string; dimension?: string; desc?: boolean; } export interface RunReportInput extends PropertyId { startDate: string; endDate: string; dimensions: string[]; metrics: string[]; dimensionFilter?: DimensionFilter; orderBy?: OrderBy; limit?: number; } export interface ReportRow { dimensions: Record<string, string>; metrics: Record<string, number | string>; } export interface RunReportOutput { rows: ReportRow[]; rowCount: number; totals?: Record<string, number | string>; metadata?: { dataLossFromOtherRow: boolean; }; }
• src/server.ts:579-606 (registration)

  Server-side dispatch handler that maps tool arguments to runReport function call upon 'run_report' invocation.
  case "run_report": return await runReport({ propertyId: args.propertyId as string | undefined, startDate: args.startDate as string, endDate: args.endDate as string, dimensions: args.dimensions as string[], metrics: args.metrics as string[], dimensionFilter: args.dimensionFilter as | { fieldName: string; stringFilter: { matchType: | "EXACT" | "BEGINS_WITH" | "CONTAINS" | "ENDS_WITH" | "REGEXP"; value: string; caseSensitive?: boolean; }; } | undefined, orderBy: args.orderBy as | { metric?: string; dimension?: string; desc?: boolean } | undefined, limit: args.limit as number | undefined, });
• src/tools/basic/index.ts:3-3 (helper)

  Re-export of the runReport handler for easy import in server.ts.
  export { runReport } from "./runReport.js";