ga4_all_paid_performance

Instructions

Implementation Reference

• src/index.ts:73-80 (registration)

  Registers the 'ga4_all_paid_performance' tool on the MCP server with its description, schema, and handler.

  server.tool(
    "ga4_all_paid_performance",
    "Paid: all paid channels (Search + Social + Video + Display + Other) broken down by channel × campaign × source × medium, with cost and ROAS.",
    allPaidSchema,
    async (args) => {
      try { return ok(await allPaidPerformance(args)); } catch (e) { return err(e); }
    }
  );

• src/tools/paid.ts:64-65 (schema)

  Schema for all paid channels: accepts start_date, end_date, property_id, and limit (spread from common).

  // All paid channels (Paid Search, Paid Social, Paid Video, Display, Paid Other)
  export const allPaidSchema = { ...common };

• src/tools/paid.ts:67-96 (handler)

  Executes a GA4 Data API runReport query filtering for all paid channels (sessionDefaultChannelGroup CONTAINS 'Paid'), broken down by channel, campaign, source, and medium, returning sessions, conversions, revenue, cost, and ROAS.

  export async function allPaidPerformance(args: z.infer<z.ZodObject<typeof allPaidSchema>>) {
    const [res] = await getClient().runReport({
      property: getProperty(args.property_id),
      dateRanges: [{ startDate: args.start_date, endDate: args.end_date }],
      dimensions: [
        { name: "sessionDefaultChannelGroup" },
        { name: "sessionCampaignName" },
        { name: "sessionSource" },
        { name: "sessionMedium" },
      ],
      metrics: [
        { name: "sessions" },
        { name: "conversions" },
        { name: "keyEvents" },
        { name: "totalRevenue" },
        { name: "advertiserAdClicks" },
        { name: "advertiserAdCost" },
        { name: "returnOnAdSpend" },
      ],
      dimensionFilter: {
        filter: {
          fieldName: "sessionDefaultChannelGroup",
          stringFilter: { matchType: "CONTAINS", value: "Paid" },
        },
      },
      orderBys: [{ metric: { metricName: "advertiserAdCost" }, desc: true }],
      limit: args.limit as unknown as number,
    });
    return formatReport(res);
  }

• src/tools/paid.ts:11-25 (helper)

  Shared helper that transforms the GA4 API raw response into a structured { rowCount, rows } format, mapping dimension and metric headers to cell values.

  function formatReport(res: any) {
    const rows = (res.rows ?? []).map((r: any) => {
      const out: Record<string, string | number> = {};
      (res.dimensionHeaders ?? []).forEach((h: any, i: number) => {
        out[h.name] = r.dimensionValues?.[i]?.value ?? "";
      });
      (res.metricHeaders ?? []).forEach((h: any, i: number) => {
        const v = r.metricValues?.[i]?.value ?? "0";
        const n = Number(v);
        out[h.name] = Number.isFinite(n) ? n : v;
      });
      return out;
    });
    return { rowCount: res.rowCount ?? rows.length, rows };
  }

• src/index.ts:17-24 (registration)

  Imports the allPaidPerformance handler and allPaidSchema from src/tools/paid.ts at the top of the entry point.

  import {
    allPaidPerformance,
    allPaidSchema,
    googleAdsPerformance,
    googleAdsSchema,
    paidSearchPerformance,
    paidSearchSchema,
  } from "./tools/paid.js";