gads_geo_performance

Instructions

Implementation Reference

• src/tools/performance.ts:16-43 (handler)

  The main handler function for the 'gads_geo_performance' tool. Queries Google Ads geographic_view table for performance broken down by location (city, region, country). Accepts optional customer_id, start_date, end_date, campaign_id, and limit parameters.

  export async function geoPerformance(args: z.infer<z.ZodObject<typeof geoPerformanceSchema>>) {
    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 rows = await customer.query(`
      SELECT
        campaign.id,
        campaign.name,
        geographic_view.country_criterion_id,
        geographic_view.location_type,
        segments.geo_target_city,
        segments.geo_target_region,
        segments.geo_target_country,
        metrics.impressions,
        metrics.clicks,
        metrics.ctr,
        metrics.cost_micros,
        metrics.conversions,
        metrics.conversions_value
      FROM geographic_view
      WHERE segments.date BETWEEN '${start}' AND '${end}'
        ${campaignClause}
      ORDER BY metrics.cost_micros DESC
      LIMIT ${args.limit}
    `);
    return { rowCount: rows.length, rows };
  }

• src/tools/performance.ts:10-14 (schema)

  Zod schema for geoPerformance: defines input validation for customer_id, start_date, end_date, campaign_id (optional filter), and limit (default 100, max 10000).

  export const geoPerformanceSchema = {
    ...baseArgs,
    campaign_id: z.string().optional().describe("Filter to a specific campaign ID"),
    limit: z.number().int().positive().max(10000).default(100),
  };

• src/index.ts:183-188 (registration)

  Registration of the 'gads_geo_performance' tool with the MCP server, including its description and wiring to the geoPerformance handler and geoPerformanceSchema.

  server.tool(
    "gads_geo_performance",
    "Performance broken down by geographic location (country, region, city). Surfaces top and bottom geo segments by cost and conversions.",
    geoPerformanceSchema,
    async (args) => { try { return ok(await geoPerformance(args)); } catch (e) { return err(e); } }
  );

• src/tools/performance.ts:4-8 (helper)

  Base schema arguments (customer_id, start_date, end_date) reused by geoPerformanceSchema via spread operator.

  const baseArgs = {
    customer_id: z.string().optional().describe("Override GOOGLE_ADS_CUSTOMER_ID for this call"),
    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"),
  };