gads_list_audiences
List remarketing audiences and customer match lists with size, eligibility, and match rate. Identify available user lists for targeting in Google Ads campaigns.
Instructions
List user lists (remarketing audiences, customer match lists) in the account with size, eligibility, and match rate.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | No | Override GOOGLE_ADS_CUSTOMER_ID for this call | |
| limit | No |
Implementation Reference
- src/tools/audiences.ts:9-29 (handler)The handler function `listAudiences` that executes the tool logic for gads_list_audiences. It queries Google Ads API for user list data (remarketing audiences, customer match lists) with fields like id, name, description, type, membership_status, size_for_display, size_for_search, eligible_for_search, eligible_for_display, and match_rate_percentage.
export async function listAudiences(args: z.infer<z.ZodObject<typeof listAudiencesSchema>>) { const customer = getCustomer(args.customer_id); const rows = await customer.query(` SELECT user_list.id, user_list.name, user_list.description, user_list.type, user_list.membership_status, user_list.size_for_display, user_list.size_for_search, user_list.eligible_for_search, user_list.eligible_for_display, user_list.match_rate_percentage FROM user_list WHERE user_list.membership_status = 'OPEN' ORDER BY user_list.size_for_search DESC LIMIT ${args.limit} `); return { rowCount: rows.length, rows }; } - src/tools/audiences.ts:4-7 (schema)The input schema `listAudiencesSchema` defining optional customer_id override and a limit (max 10000, default 100) for the gads_list_audiences tool.
export const listAudiencesSchema = { customer_id: z.string().optional().describe("Override GOOGLE_ADS_CUSTOMER_ID for this call"), limit: z.number().int().positive().max(10000).default(100), }; - src/index.ts:167-172 (registration)Registration of `gads_list_audiences` tool on the MCP server with its description, schema, and handler.
server.tool( "gads_list_audiences", "List user lists (remarketing audiences, customer match lists) in the account with size, eligibility, and match rate.", listAudiencesSchema, async (args) => { try { return ok(await listAudiences(args)); } catch (e) { return err(e); } } ); - src/index.ts:23-28 (helper)Import of `listAudiences` and `listAudiencesSchema` from the audiences module into the main index file.
import { campaignAudienceTargeting, campaignAudienceTargetingSchema, listAudiences, listAudiencesSchema, } from "./tools/audiences.js";