Google Ads MCP: Transparency Center tools and limits
How Proxy's Google Ads MCP reads the Ads Transparency Center: advertiser lookup, ad lists, creative details, exact parameters, paging and credit cost.
Most servers called a “Google Ads MCP” manage your own Google Ads account. Proxy does a different job: it reads the public Google Ads Transparency Center, so an assistant can show what any advertiser runs on Search, YouTube and Display. It is read-only and never connects to a Google Ads account.
This page documents exactly how the three Google tools behave. For the short parameter tables, see the Google tool reference.
Connect
One endpoint serves every client and every platform:
https://mcp.useproxy.dev/mcp?ref=docs
Sign-in is OAuth, with no API keys. Steps per client are in Connect your client, with deeper notes for Claude, ChatGPT and Claude Code.
The three-step chain
Google research always runs in the same order:
get_google_platform_idturns a brand name into advertiser IDs and domains.get_google_adslists the ads for one advertiser ID or one domain.get_google_ad_detailsopens an ad to read its copy, regions and impressions.
The list step returns no ad copy. Headlines and descriptions only exist at step 3.
get_google_platform_id
| Parameter | Type | Behaviour |
|---|---|---|
brand_name |
string or list | Bare brand name or bare domain. A list is looked up in parallel |
- Matching is literal. Pass
Purinaorpurina.com.mx, not both together, and no country or city. - Built-in fallbacks. If the exact query finds nothing, the server retries with the bare domain, the bare name, or the name without a trailing country. The response then says which query produced the results. These retries cost nothing extra.
- Two result types.
advertisers(name,advertiser_id, region) andwebsites(domain). They can point to different accounts for the same brand, so the assistant is told to query both. - Results span all countries. Pick the advertiser whose region matches your market.
- Zero matches returns a hint to retry with the bare name or domain. Unlike Meta, there is no keyword fallback.
get_google_ads
| Parameter | Default | Accepted values and behaviour |
|---|---|---|
domain |
none | For example nike.com. Company-wide search |
advertiser_id |
none | From the lookup. Targets one regional entity |
limit |
100 | Maximum 1000. Fetched in pages, up to 10 pages per call |
topic |
none | Topic filter. political requires region |
region |
none | Region code such as US |
cursor |
none | Reads the next window of a result already fetched |
One of domain or advertiser_id is required. Calling with neither, or with topic political and no region, returns an error.
Each ad row carries ad_url, advertiser_id, advertiser_name, format, domain, first_shown and last_shown. format is text, image or video.
Re-running the same advertiser later reports what changed since your last fetch: how many ads are new and how many are no longer returned.
get_google_ad_details
| Parameter | Type | Behaviour |
|---|---|---|
ad_url |
string or list | Transparency Center ad URL from get_google_ads |
A single URL returns:
advertiser_id,creative_id,format,first_shown,last_shownoverall_impressions, which can be emptyregions, the region codes the ad is shown invariations, each withheadline,description,destinationUrl,allTextand, for image ads,imageUrl
A list of URLs is fetched in parallel and returns a summary per URL: format, variation_count and image_urls. To read the copy of a specific ad, ask for that ad on its own.
Image URLs can be passed to analyze_ad_image.
What it never contains
- Spend, clicks, CPC or conversions. Google does not publish them.
- The keywords an ad bids on.
- Impressions at list level. Ranges appear only in details, and can be empty there too.
- Anything from your own Google Ads account.
Paging and cursors
get_google_adspages upstream until it reacheslimitor 10 pages.- A large list is returned in windows of about 40,000 characters. The rest is stored for 24 hours and read with a cursor of the form
rs:<id>:<offset>, at no credit cost. - After 24 hours the cursor returns an error asking to re-run the call.
Credit cost
| Call | Credits |
|---|---|
get_google_platform_id |
1 per brand, including any fallback retries |
get_google_ads |
1 per upstream page fetched, up to 10 |
get_google_ad_details |
1 per ad URL. Duplicate URLs in a list are fetched once |
Reading an rs: cursor |
0 |
limit is the cost lever. Ask for 20 to 30 ads for a quick look and keep 100 for a full audit.
Free is 20 credits a day with no card, Pro is $50 a month for 100 a day, and Max is $100 a month for 250 a day. There is no overage billing. See Credits and plans.
Failure modes
| Situation | What the tool returns |
|---|---|
| Name with a country or city attached | Results for the fallback query, with a note naming it |
| One brand in a list fails | That brand is marked “lookup failed, not confirmed absent” |
| No ads for the identifier | Zero ads. Try the other identifier type before concluding |
| Ad removed since it was listed | “Google returned no details for this ad_url” |
| One URL in a list fails | That URL carries an error; the others still return |
| Credits run out mid-list | The first URLs are fetched; the rest are marked as not fetched |
| Rate limit, timeout or outage | A short retry hint. Raw upstream errors are never passed through |
Worked prompts
Find [brand]'s Google advertiser accounts and domains.
get_google_platform_id. 1 credit.
Pull 30 Google ads for [domain] and group them by format.
get_google_ads with domain and limit 30. Usually 1 credit.
Show every headline and description variation in [brand]'s newest text ad.
get_google_platform_id, get_google_ads, then get_google_ad_details with one ad_url. 3 credits.
Which regions is [brand] showing its five longest-running Google ads in?
get_google_ads, then five single get_google_ad_details calls for regions. 6 credits plus the lookup.
Find three competitors of [domain] and compare their Google ad formats.
search_competitors, then one get_google_ads per domain. About 4 credits at 30 ads each.