google-ads-mcp-worker

A remote MCP server for the Google Ads API, running on Cloudflare Workers.

Read-only access to your Google Ads data through GAQL, reachable over HTTPS from any MCP client — no local process, no Python environment, no container. Implements the 2026-07-28 MCP specification: stateless Streamable HTTP, server/discover, no session ids.

Status: early. The protocol layer is exercised by tests and by the smoke script below. The tool surface is small on purpose and will grow with real use. Issues and PRs welcome.

Why this exists

Google ships an official MCP server (Python, Apache-2.0). It is good, and if you want a local stdio server you should probably use it. This project is a different shape:

Neither replaces the other. Use whichever matches how you deploy.

Related MCP server: Google Ads MCP Server

Tools

All four are read-only (readOnlyHint: true). This server exposes no mutating tools — it never calls a mutate endpoint, so it cannot change your campaigns, budgets, or bids.

The server also ships instructions (served in server/discover) telling the model the things that otherwise cost a failed query each: metrics don't exist on manager accounts, money is in micros, query fields are snake_case while the response is camelCase.

Quickstart

1. Google Ads credentials

You need four values:

• Developer token — Google Ads manager account → Tools & Settings → API Center. Note the access levels: Test reaches test accounts only, Explorer is capped at 2,880 operations/day and blocks several services, Basic gives 15,000/day, Standard is uncapped.

• OAuth client id and secret — Google Cloud Console → APIs & Services → Credentials → OAuth client ID, with the Google Ads API enabled on the project. Choose Desktop app unless you have a reason not to: it allows the loopback redirect the helper below uses, with nothing to register.

• Refresh token — for the scope https://www.googleapis.com/auth/adwords. If you don't have one:

  node scripts/get-refresh-token.mjs path/to/your-oauth-client.json

  It runs the consent flow against a local loopback and writes the client id, secret and refresh token into .dev.vars — no copy-pasting a token through your scrollback. Pass --print if you'd rather handle it yourself.

Two things that catch people out:

• A service account will not work without domain-wide delegation. The Google Ads API expects a user credential.

• While your OAuth consent screen is in Testing, refresh tokens expire after 7 days. Publish the app before you rely on one for a deployed server, or the Worker starts failing with invalid_grant a week later.

2. Install and configure

git clone https://github.com/marcosvb1/google-ads-mcp-worker
cd google-ads-mcp-worker
npm install
cp .dev.vars.example .dev.vars   # fill it in

3. Run it locally

npm run dev

Then either point the MCP Inspector at http://localhost:8787/mcp (npm run inspect), or run the smoke script:

./scripts/smoke.sh

4. Deploy

Load the four Google secrets straight from a credentials file, without them passing through your terminal:

./scripts/set-secrets.sh path/to/credentials.json

Or set each one by hand:

npx wrangler secret put GOOGLE_ADS_DEVELOPER_TOKEN
npx wrangler secret put GOOGLE_ADS_CLIENT_ID
npx wrangler secret put GOOGLE_ADS_CLIENT_SECRET
npx wrangler secret put GOOGLE_ADS_REFRESH_TOKEN

Then pick an auth gate — without one the server refuses every request — and ship:

npx wrangler secret put MCP_SHARED_SECRET
npx wrangler deploy

Serving more than one manager account

Developer tokens are issued per manager account and carry their own daily operation quota, and a client's MCC usually arrives with its own token and its own login. So "which credentials" is a property of the account being queried, not of the deployment.

Suffix any credential variable with _<PROFILE> to add a profile:

# default profile
npx wrangler secret put GOOGLE_ADS_DEVELOPER_TOKEN

# profile "sirio" — its own token and manager, reusing the default login
npx wrangler secret put GOOGLE_ADS_DEVELOPER_TOKEN_SIRIO
# GOOGLE_ADS_LOGIN_CUSTOMER_ID_SIRIO goes in wrangler.jsonc (not a secret)

Or in one step, per profile:

./scripts/set-secrets.sh --profile sirio path/to/credentials.json

Then every tool takes a profile argument. It is typed as an enum of the profiles you actually configured, so a wrong value fails schema validation with the real list rather than as a confusing permission error from Google. Anything a profile leaves unset is inherited from the default, so sharing one Google login across several managers costs one variable per profile. Results echo back which profile served them.

With a single profile configured, the argument is not advertised at all — nothing to think about until you need it.

Authentication

Two separate questions, easy to conflate:

1. How the Worker talks to Google — one set of credentials, held as Worker secrets. Every caller of this server shares that identity.

2. Who may call the Worker — configured below. Because of (1), this is the gate that matters: whoever reaches /mcp can read whatever those credentials can read.

Three modes, resolved in order. With none configured the server denies every request — that is deliberate.

Narrow the blast radius further with GOOGLE_ADS_ALLOWED_CUSTOMER_IDS, a comma-separated allowlist of the accounts this deployment may query. Any other id is refused before a request reaches Google.

If you put it behind a Cloudflare MCP Portal

A MCP Server Portal gives you tool curation, per-call logging and a single endpoint for several servers. It is not a security perimeter for this Worker: Cloudflare's own documentation warns that blocked users can still reach the server's direct URL and bypass the Access policy. Keep MCP_SHARED_SECRET set (the portal stores it as the upstream credential), or configure Access on the Worker itself.

Connecting a client

{
  "mcpServers": {
    "google-ads": {
      "type": "http",
      "url": "https://google-ads-mcp-worker.<your-subdomain>.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <MCP_SHARED_SECRET>" }
    }
  }
}

Clients that predate the 2026-07-28 revision still work: the handler serves 2025-era requests through its stateless fallback. GET and DELETE on /mcp answer 405, since those were session operations and there are no sessions.

Configuration reference

Any of the five GOOGLE_ADS_* credential variables may carry a _<PROFILE> suffix to define an additional profile — see above. GOOGLE_ADS_API_VERSION and GOOGLE_ADS_ALLOWED_CUSTOMER_IDS are deployment-wide and are never suffixed.

Secrets may also be supplied through the Secrets Store; the code reads either a plain string binding or a store binding.

Things that will bite you

Collected from the API's sharper edges — most of them cost somebody a debugging session.

• API versions are retired abruptly. On 2026-08-07, v21 began returning Version v21 is deprecated. Requests to this version will be blocked. mid-session, and a validateOnly dry run had passed minutes earlier. A clean dry run does not guarantee the next call succeeds. That is why the version is a var: bump GOOGLE_ADS_API_VERSION and redeploy. Check the sunset dates.

• login-customer-id is required for MCC access. Reaching a client account through a manager without it fails with USER_PERMISSION_DENIED, and the failure does not name the missing header.

• Manager accounts have no metrics. Query a client account; use list_customer_clients to find one.

• Query is snake_case, response is camelCase. cost_micros in GAQL comes back as costMicros. Read the returned fieldMask.

• Money is micros. Divide by 1,000,000.

• Brazil: Google does not pass PIS/COFINS through to the advertiser, so cost_micros / 1e6 is the amount actually billed — no gross-up. This is not symmetric with Meta Ads, which does pass tax through. A report combining both channels must not apply the same factor to both.

• Pages cap at 10,000 rows. Ignoring next_page_token silently truncates large queries.

• Rate limits are a token bucket, not a fixed number. Expect RESOURCE_TEMPORARILY_EXHAUSTED under load and back off.

• A Worker has 6 simultaneous outbound connections. Relevant if you fan out across many accounts.

Design notes

• googleAds:search, not searchStream. searchStream returns the whole result set in one response — and, uniquely in this API, wrapped in a JSON array rather than an object. That is a poor fit for a 128 MB Worker and gives the caller no way to stop early. Paging keeps every response bounded.

• No Durable Object. MCP 2026-07-28 is stateless, and this server is a thin REST proxy that holds nothing between requests. A fresh McpServer is built per request; the handler is built once per isolate so that subscriptions/listen streams are not orphaned.

• No nodejs_compat. @modelcontextprotocol/server has a workerd export condition and bundles a @cfworker/json-schema validator, because Ajv compiles with new Function, which workerd forbids.

• Access tokens are cached per isolate and refreshed a minute early. It is only ever a cache — a cold isolate simply fetches again.

• Response size is capped at 60k characters, and the tool says so rather than returning truncated (invalid) JSON.

Contributing

See CONTRIBUTING.md. The short version: npm run typecheck && npm test must pass, and new tools stay read-only unless there is a discussion first.

License

Apache-2.0. Not an official Google product, and not affiliated with Google.