Skip to main content
Glama
Google Ads MCP Server

Google Ads MCP Server

by ccsmatt

Google Ads MCP Server

A read-only Model Context Protocol server that lets Claude query Google Ads accounts under a manager (MCC) account. Deploy it once (for example on Railway), add it to your Claude Team plan as a custom connector, and anyone on the team can ask things like:

  • "Which campaigns spent the most last month, and what was their cost per conversion?"

  • "Show search terms in account 123-456-7890 that cost over $20 in the last 30 days with zero conversions"

  • "Which keywords have a quality score below 5 and still get clicks?"

  • "Compare ad group CTR this month vs last month for the Brand campaign"

  • "What changed in this account in the last two weeks, and could it explain the drop in calls?"

  • "What's our cost per lead for phone calls vs form fills by campaign last month?"

  • "Find every Christmas or holiday campaign across all clients last December and what each spent"

It is read-only. Google offers no read-only Ads scope, so the token uses https://www.googleapis.com/auth/adwords, but the server only calls the read-only googleAds:searchStream and customers:listAccessibleCustomers endpoints, refuses to call any other endpoint, has no mutate code at all, and run_gaql rejects anything that isn't a SELECT. For a guarantee enforced by Google, create the refresh token with a Google user that has Read only access to the MCC (step 2).

Based on ccsmatt/ga-mcp-server, itself derived from sofianbettayeb/gsc-mcp-server by Sofian Bettayeb (MIT). The HTTP transport, auth and deployment setup come from those projects; the tools are new.

Tools

Tool

What it does

list_accounts

Client accounts under the MCC: customer ID, name, currency, time zone, status. name_filter finds a client by name words or ID; returns 100 accounts by default (max 1000)

run_gaql

Any read-only GAQL SELECT query against one account; rows returned as JSON

campaign_performance

Per campaign: status, impressions, clicks, cost, conversions, conversion value, CTR, avg CPC, cost/conv

ad_group_performance

Same metrics per ad group (optionally one campaign)

search_terms

Search terms with matched keyword, campaign, ad group, clicks, cost, conversions; filters for min cost, min clicks, zero conversions

keyword_performance

Keywords with quality score (and its components) plus performance metrics

ad_performance

Ads with type, status, approval status, ad strength, final URL, headlines/descriptions, plus performance metrics

conversion_breakdown

Conversions per conversion action (calls, forms, ...) per campaign, with cost per conversion for each: true cost per lead

change_history

Who changed what and when (last 30 days max), with old and new values for each changed field

search_campaigns

Finds campaigns by name (case-insensitive regex, e.g. christmas|holiday) across every enabled client account under the MCC, in parallel; one list sorted by cost, plus a summary of accounts searched, accounts that errored, and total spend per currency

Details:

  • Dates: the report tools take either date_range (a GAQL preset such as LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH; default LAST_30_DAYS) or start_date + end_date (YYYY-MM-DD).

  • Money: the report tools return costs in the account's currency (cost_micros / 1,000,000). The currency is shown at the top of each result. run_gaql returns raw API values, so _micros fields stay in micros.

  • Row cap: results are capped at limit rows (default 100, max 1000). Output includes truncated: true and a note when there were more.

  • API version: the server uses Google Ads API v26, set by GOOGLE_ADS_API_VERSION in src/ads-client.ts. Google sunsets each version about a year after release (release notes), so bump it when needed.

Related MCP server: Google Ads MCP Server

How it works

  • One HTTP endpoint, POST /mcp (stateless streamable HTTP), plus GET /healthz for health checks.

  • Every /mcp request must carry Authorization: Bearer <MCP_AUTH_TOKEN>. The server refuses to start if MCP_AUTH_TOKEN is not set.

  • The server reads Google Ads as one Google user (whoever created the refresh token), through one MCC. Every API request sends login-customer-id set to the MCC ID, plus the developer-token header if you set one. Everyone who uses the connector sees every account under that MCC.

  • API access (Test, Explorer, Basic or Standard) belongs to the Google Cloud project that owns the OAuth client, not to a developer token. Google sunset developer tokens on September 9, 2026.

  • All credentials come from environment variables. Nothing is written to disk.

Environment variables

Variable

Required

Description

GOOGLE_ADS_CLIENT_ID

yes

OAuth client ID (Desktop app type)

GOOGLE_ADS_CLIENT_SECRET

yes

OAuth client secret

GOOGLE_ADS_REFRESH_TOKEN

yes

From npm run setup-auth (step 3)

GOOGLE_ADS_LOGIN_CUSTOMER_ID

yes

Your MCC customer ID, e.g. 123-456-7890 (dashes are stripped)

GOOGLE_ADS_DEVELOPER_TOKEN

no

Optional. Sent if set, but ignored by Google since September 9, 2026

MCP_AUTH_TOKEN

yes

Long random string Claude must send as a Bearer token

PORT

no

Listen port (default 8080; Railway sets this for you)

1. Google Cloud project and API access

Google Ads API access levels are granted to a Google Cloud project: the one that owns the OAuth client you create in step 2. See Access levels.

Level

Real (production) accounts

Daily limit

How you get it

Test

No, test accounts only

15,000 ops

Automatic when you enable the API

Explorer

Yes

2,880 ops (production)

Apply; often approved automatically

Basic

Yes

15,000 ops

Apply; brand verification required

Standard

Yes

Unlimited

Detailed manual review

Explorer is enough for this server: it is read-only reporting, and each tool call is one search request.

  1. Go to Google Cloud Console and pick the project:

    • If you used the Google Ads API before September 9, 2026, Google moved your old developer token's access level to the Cloud project(s) used with it in the previous 90 days. Use that project, so you keep the level.

    • Otherwise create a new project just for this server, inside your Google Workspace organization if you have one. Don't add the Ads scope to another server's project: adwords is a sensitive scope, so it changes that project's verification status and can trigger Google's "This app is blocked" screen.

  2. Enable the API (APIs & Services > Library): search for Google Ads API and click Enable. The project now has Test access.

  3. Apply for production access: open the project's Google Ads API page (APIs & Services > Enabled APIs & services > Google Ads API) and apply for Explorer (or Basic) access from its Overview. Until this is granted, calls to real accounts fail with CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION.

  4. Configure the OAuth consent screen (Google Auth Platform):

    • Branding: app name (e.g. "Google Ads MCP") and your support email.

    • Audience:

      • If your Google account is part of a Google Workspace organization, choose Internal. Tokens don't expire and no verification is needed.

      • Otherwise choose External, add yourself as a test user, then Publish app (set it to In production). Apps left in Testing issue refresh tokens that expire after 7 days. An unverified production app shows an "unverified app" warning during consent; as the owner you can click Advanced > Go to ... (unsafe) to continue.

    • Data Access: add the scope https://www.googleapis.com/auth/adwords (shown as ".../auth/adwords").

2. Create the OAuth client

  1. Google Auth Platform > Clients > Create client.

  2. Application type: Desktop app. Give it a name and click Create.

  3. Copy the Client ID and Client secret. Create the client in the project from step 1, since that project's access level is the one that counts. Don't download the JSON into this repo. It's git-ignored, but you don't need it.

Make sure the Google account you'll sign in with has access to the MCC (Google Ads > Admin > Access and security).

Recommended: use a Read only Google Ads user. The adwords scope can't be narrowed, but the token can never do more than its Google user can. In the MCC go to Admin > Access and security > + (add user), invite a Google account with access level Read only, and sign in as that account in step 3. Google Ads itself then rejects any change, whatever the software does.

3. Get a refresh token

You need Node.js 22+ and a copy of this repo.

git clone https://github.com/ccsmatt/google-ads-mcp-server.git
cd google-ads-mcp-server
npm install

Then run the helper with your client ID and secret as environment variables.

PowerShell (Windows):

$env:GOOGLE_ADS_CLIENT_ID = "your-client-id.apps.googleusercontent.com"
$env:GOOGLE_ADS_CLIENT_SECRET = "your-client-secret"
npm run setup-auth

macOS / Linux:

GOOGLE_ADS_CLIENT_ID="your-client-id.apps.googleusercontent.com" GOOGLE_ADS_CLIENT_SECRET="your-client-secret" npm run setup-auth

The script:

  1. Prints a Google consent URL. Open it in an incognito/private window and sign in with the Google account that has access to your MCC.

  2. Approve access. Google describes it as "See, edit, create and delete your Google Ads accounts and data", because that's the only Ads scope; this server only reads.

  3. Your browser then goes to http://localhost/?code=... and shows a "can't connect" page. That's expected. Copy the full address from the address bar (or just the code value) and paste it into the terminal.

  4. The script prints only the refresh token. Copy it somewhere safe (e.g. your password manager).

Nothing is written to disk. Close the terminal afterwards so the client secret isn't left in its environment.

If you get invalid_grant, the code expired or was already used. Run it again and paste promptly.

4. Choose an MCP auth token

MCP_AUTH_TOKEN is the password Claude uses to call your server. Generate a long random one:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

5. Deploy to Railway

  1. In Railway, click New Project > Deploy from GitHub repo and pick google-ads-mcp-server. Railway finds the Dockerfile and builds with it.

  2. Open the service > Variables and add GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID and MCP_AUTH_TOKEN. Don't set PORT; Railway provides it.

  3. Settings > Networking > Generate Domain to get a public URL like https://google-ads-mcp-server-production.up.railway.app.

  4. Optional: Settings > Deploy > Healthcheck Path = /healthz.

  5. Check it: opening https://<your-domain>/healthz should show {"status":"ok"}, and the deploy logs should say google-ads-mcp-server listening on port .... If the logs say a variable is missing, fix it under Variables; Railway redeploys automatically.

Your MCP endpoint is https://<your-domain>/mcp.

6. Add it to Claude (Team plan)

An Owner of the Claude Team organization does this once:

  1. Go to Organization settings > Connectors, select Add, then Custom (choose Web if asked).

  2. Name: e.g. "Google Ads". MCP server URL: https://<your-domain>/mcp.

  3. Authentication: No sign-in.

  4. Request headers: header name authorization, value Bearer <your MCP_AUTH_TOKEN>. Type the word Bearer, a space, then the token; Claude sends the value exactly as entered. Mark it Required.

  5. Click Add.

Team members then go to Customize > Connectors, find the connector with the Custom label and click Connect. In a chat, turn it on from the + menu > Connectors.

To change the token later, update MCP_AUTH_TOKEN in Railway, then remove and re-add the connector with the new header (headers can't be edited after saving).

Claude Code (CLI)

claude mcp add --transport http google-ads https://<your-domain>/mcp --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

Local development

cp .env.example .env    # fill in real values; .env is git-ignored
npm run build
npm start               # or: npm run dev

npm start doesn't load .env by itself, so export the variables in your shell first (or use your editor's env support). Then check http://localhost:8080/healthz.

Troubleshooting

Message

Fix

only has Test access (CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION)

The Cloud project that owns the OAuth client needs Explorer or Basic access (step 1.3).

generic authorization error (AUTHORIZATION_ERROR)

Known Google issue for projects upgraded after September 9, 2026; Google says a fix is rolling out. Otherwise check MCC access.

Google rejected the developer token

Remove GOOGLE_ADS_DEVELOPER_TOKEN; it's optional now.

customer isn't accessible through the MCC

The account isn't linked under GOOGLE_ADS_LOGIN_CUSTOMER_ID, or the token's Google user can't access the MCC.

Invalid GAQL query

Check field names (snake_case), field/resource compatibility, and quoting. The Query Builder helps.

Google Ads API is not enabled

Enable Google Ads API in the same Cloud project as the OAuth client.

"This app is blocked" during setup-auth

The consent screen is External and unverified, and adwords is a sensitive scope. Use a project in your Workspace organization with Audience = Internal. If it's still blocked, a Workspace admin must mark the OAuth client as Trusted (Admin console > Security > Access and data control > API controls > Manage Third-Party App Access).

invalid_grant

Refresh token revoked or expired (7-day expiry if the consent screen is External + Testing). Re-run npm run setup-auth and update GOOGLE_ADS_REFRESH_TOKEN.

Not found (404) on every call

The API version may be sunset. Bump GOOGLE_ADS_API_VERSION in src/ads-client.ts.

401 Unauthorized from /mcp

The connector isn't sending Authorization: Bearer <MCP_AUTH_TOKEN>, or the value doesn't match exactly (check for a missing Bearer ).

Server exits at startup

Read the deploy log: it names the missing variable.

Security notes

  • Never commit .env, OAuth client JSON or tokens. .gitignore and .dockerignore block the usual file names.

  • The refresh token carries all of its Google user's Google Ads permissions, even though this server only reads. Create it with a Read only user (step 2) so a leaked token can't change anything. Store it only in Railway variables, and revoke it any time at Google Account permissions.

  • Anyone with MCP_AUTH_TOKEN and the URL can read every account under the MCC. Rotate the token if it leaks.

Privacy

See PRIVACY.md and TERMS.md.

License

MIT. See LICENSE. Originally derived from gsc-mcp-server by Sofian Bettayeb.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language access to Google Ads campaigns, accounts, and performance metrics via Claude, with tools for managing ad groups, keywords, budgets, and visualizing data.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude Desktop to your Google Ads account, allowing you to analyze and manage campaigns, ad groups, and keywords using natural language.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language analysis and management of Google Ads accounts, campaigns, keywords, budgets, and performance metrics through Claude.
      MIT