gads_conversions_by_campaign

Instructions

Implementation Reference

• src/index.ts:119-124 (registration)

  Registers the 'gads_conversions_by_campaign' tool with the MCP server, passing the schema and handler function.

  server.tool(
    "gads_conversions_by_campaign",
    "Conversions and conversion value broken down by campaign × conversion action. Sorted by conversions desc. Default last 28 days.",
    conversionsByCampaignSchema,
    async (args) => { try { return ok(await conversionsByCampaign(args)); } catch (e) { return err(e); } }
  );

• src/tools/conversions.ts:4-9 (schema)

  Defines the input schema for conversionsByCampaign: start_date, end_date, customer_id, and limit with defaults.

  export const conversionsByCampaignSchema = {
    start_date: z.string().default(DEFAULT_START),
    end_date: z.string().default(DEFAULT_END),
    customer_id: z.string().optional(),
    limit: z.number().int().positive().max(10000).default(100),
  };

• src/tools/conversions.ts:11-31 (handler)

  The async handler that executes a GAQL query against Google Ads API, returning conversion metrics (conversions, conversion value, cost per conversion, value per conversion) grouped by campaign and conversion action, sorted by conversions descending.

  export async function conversionsByCampaign(args: z.infer<z.ZodObject<typeof conversionsByCampaignSchema>>) {
    const customer = getCustomer(args.customer_id);
    const start = resolveDate(args.start_date);
    const end = resolveDate(args.end_date);
    const rows = await customer.query(`
      SELECT
        campaign.id,
        campaign.name,
        segments.conversion_action_name,
        metrics.conversions,
        metrics.conversions_value,
        metrics.cost_per_conversion,
        metrics.value_per_conversion
      FROM campaign
      WHERE segments.date BETWEEN '${start}' AND '${end}'
        AND metrics.conversions > 0
      ORDER BY metrics.conversions DESC
      LIMIT ${args.limit}
    `);
    return { rowCount: rows.length, rows };
  }

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

  getCustomer helper used by the handler to obtain an authenticated Google Ads Customer instance.

  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 });
  }

• src/client.ts:39-49 (helper)

  Default date constants (DEFAULT_START, DEFAULT_END) and resolveDate helper used to parse date arguments.

  export const DEFAULT_START = "28daysAgo";
  export const DEFAULT_END = "yesterday";
  
  export function resolveDate(d: string): string {
    if (/^\d{4}-\d{2}-\d{2}$/.test(d)) return d;
    if (d === "today") return toISO(new Date());
    if (d === "yesterday") return toISO(offsetDays(new Date(), -1));
    const m = d.match(/^(\d+)daysAgo$/);
    if (m) return toISO(offsetDays(new Date(), -parseInt(m[1], 10)));
    throw new GoogleAdsError(`Unrecognized date: ${d}. Use YYYY-MM-DD, today, yesterday, or NdaysAgo.`);
  }