For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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:

  1. get_google_platform_id turns a brand name into advertiser IDs and domains.
  2. get_google_ads lists the ads for one advertiser ID or one domain.
  3. get_google_ad_details opens 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 Purina or purina.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) and websites (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_shown
  • overall_impressions, which can be empty
  • regions, the region codes the ad is shown in
  • variations, each with headline, description, destinationUrl, allText and, 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_ads pages upstream until it reaches limit or 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.

Guides

Was this page helpful?