gads_campaign_performance

Instructions

Implementation Reference

• src/index.ts:87-92 (registration)

  Registration of the 'gads_campaign_performance' tool with MCP server, linking the schema and handler function.

  server.tool(
    "gads_campaign_performance",
    "Campaign-level performance: impressions, clicks, CTR, avg CPC, cost, conversions, conv value, CPA, ROAS. Defaults to last 28 days, enabled campaigns, sorted by cost desc.",
    campaignPerformanceSchema,
    async (args) => { try { return ok(await campaignPerformance(args)); } catch (e) { return err(e); } }
  );

• src/tools/campaigns.ts:43-47 (schema)

  Schema definition for campaignPerformance inputs: dateRange (start_date, end_date, customer_id, limit), status filter, and order_by.

  export const campaignPerformanceSchema = {
    ...dateRange,
    status: z.enum(["ENABLED", "PAUSED", "REMOVED", "ALL"]).default("ENABLED"),
    order_by: z.string().default("cost_micros").describe("Metric to sort by desc: cost_micros, clicks, impressions, conversions, ctr"),
  };

• src/tools/campaigns.ts:49-86 (handler)

  Handler function that executes the GAQL query to fetch campaign performance metrics (impressions, clicks, CTR, avg CPC, cost, conversions, conv value, cost per conversion) and enriches results with computed cost in dollars and ROAS.

  export async function campaignPerformance(args: z.infer<z.ZodObject<typeof campaignPerformanceSchema>>) {
    const customer = getCustomer(args.customer_id);
    const start = resolveDate(args.start_date);
    const end = resolveDate(args.end_date);
    const statusClause = args.status === "ALL" ? "" : `AND campaign.status = '${args.status}'`;
    const rows = await customer.query(`
      SELECT
        campaign.id,
        campaign.name,
        campaign.status,
        campaign.advertising_channel_type,
        metrics.impressions,
        metrics.clicks,
        metrics.ctr,
        metrics.average_cpc,
        metrics.cost_micros,
        metrics.conversions,
        metrics.conversions_value,
        metrics.cost_per_conversion
      FROM campaign
      WHERE segments.date BETWEEN '${start}' AND '${end}'
        ${statusClause}
      ORDER BY metrics.${args.order_by} DESC
      LIMIT ${args.limit}
    `);
    const enriched = rows.map((r: any) => ({
      ...r,
      metrics: {
        ...r.metrics,
        cost: microsToDollars(r.metrics?.cost_micros),
        average_cpc_dollars: microsToDollars(r.metrics?.average_cpc),
        roas: r.metrics?.cost_micros
          ? Number(r.metrics.conversions_value ?? 0) / microsToDollars(r.metrics.cost_micros)
          : 0,
      },
    }));
    return { rowCount: enriched.length, rows: enriched };
  }

• src/tools/campaigns.ts:11-14 (helper)

  Helper function to convert micros (micro-amounts) to dollars by dividing by 1,000,000.

  function microsToDollars(micros: number | string | undefined): number {
    const n = Number(micros ?? 0);
    return Number.isFinite(n) ? n / 1_000_000 : 0;
  }

• src/client.ts:24-31 (helper)

  getCustomer helper that initializes the Google Ads API customer object used by the handler to run GAQL queries.

  export function getCustomer(override?: string): Customer {
    const refresh_token = process.env.GOOGLE_ADS_REFRESH_TOKEN;
    if (!refresh_token) throw new GoogleAdsError("GOOGLE_ADS_REFRESH_TOKEN is not set");
    const customer_id = (override ?? process.env.GOOGLE_ADS_CUSTOMER_ID ?? "").replace(/-/g, "");
    if (!customer_id) throw new GoogleAdsError("GOOGLE_ADS_CUSTOMER_ID is not set and no customer_id was passed");
    const login_customer_id = process.env.GOOGLE_ADS_LOGIN_CUSTOMER_ID?.replace(/-/g, "") || undefined;
    return getApi().Customer({ customer_id, login_customer_id, refresh_token });
  }