gads_ad_group_performance

Instructions

Implementation Reference

• src/tools/campaigns.ts:94-122 (handler)

  The main handler function that executes the 'gads_ad_group_performance' tool logic. It builds a GAQL query to fetch ad group performance data (impressions, clicks, CTR, avg CPC, cost, conversions, conversion value) filtered by date range, campaign ID, and status, with results ordered by cost descending.

  export async function adGroupPerformance(args: z.infer<z.ZodObject<typeof adGroupPerformanceSchema>>) {
    const customer = getCustomer(args.customer_id);
    const start = resolveDate(args.start_date);
    const end = resolveDate(args.end_date);
    const campaignClause = args.campaign_id ? `AND campaign.id = ${args.campaign_id}` : "";
    const statusClause = args.status === "ALL" ? "" : `AND ad_group.status = '${args.status}'`;
    const rows = await customer.query(`
      SELECT
        campaign.id,
        campaign.name,
        ad_group.id,
        ad_group.name,
        ad_group.status,
        metrics.impressions,
        metrics.clicks,
        metrics.ctr,
        metrics.average_cpc,
        metrics.cost_micros,
        metrics.conversions,
        metrics.conversions_value
      FROM ad_group
      WHERE segments.date BETWEEN '${start}' AND '${end}'
        ${campaignClause}
        ${statusClause}
      ORDER BY metrics.cost_micros DESC
      LIMIT ${args.limit}
    `);
    return { rowCount: rows.length, rows };
  }

• src/tools/campaigns.ts:88-92 (schema)

  Input schema (Zod-based) for the ad group performance tool. Includes dateRange fields (start_date, end_date, customer_id, limit), optional campaign_id filter, and status filter (defaults to ENABLED).

  export const adGroupPerformanceSchema = {
    ...dateRange,
    campaign_id: z.string().optional().describe("Filter to a specific campaign ID"),
    status: z.enum(["ENABLED", "PAUSED", "REMOVED", "ALL"]).default("ENABLED"),
  };

• src/index.ts:94-99 (registration)

  Registration of the 'gads_ad_group_performance' tool with the MCP server. Maps the tool name to its schema (adGroupPerformanceSchema) and handler (adGroupPerformance function) with a description.

  server.tool(
    "gads_ad_group_performance",
    "Ad group performance with campaign context. Optional campaign_id filter. Default last 28 days, enabled ad groups.",
    adGroupPerformanceSchema,
    async (args) => { try { return ok(await adGroupPerformance(args)); } catch (e) { return err(e); } }
  );

• src/tools/campaigns.ts:4-9 (helper)

  The dateRange helper object reused by the ad group performance schema, defining start_date, end_date, customer_id, and limit fields with defaults.

  const dateRange = {
    start_date: z.string().default(DEFAULT_START).describe("Start date: YYYY-MM-DD, NdaysAgo, yesterday, or today"),
    end_date: z.string().default(DEFAULT_END).describe("End date: YYYY-MM-DD, NdaysAgo, yesterday, or today"),
    customer_id: z.string().optional().describe("Override GOOGLE_ADS_CUSTOMER_ID for this call"),
    limit: z.number().int().positive().max(10000).default(50).describe("Max rows to return"),
  };

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

  Utility helper microsToDollars used to convert micro-amounts (used in the campaign performance handler but available in the same module).

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