Google Ads MCP Server
Read-only querying of Google Ads accounts under a manager (MCC) account: lists client accounts, runs arbitrary GAQL SELECT queries, and provides report tools for campaign, ad group, keyword, ad and search-term performance, conversion breakdowns per conversion action (cost per lead), and change history. Costs are returned in the account's currency, dates can be set via presets or explicit ranges, and results are row-capped.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Client accounts under the MCC: customer ID, name, currency, time zone, status. |
| Any read-only GAQL |
| Per campaign: status, impressions, clicks, cost, conversions, conversion value, CTR, avg CPC, cost/conv |
| Same metrics per ad group (optionally one campaign) |
| Search terms with matched keyword, campaign, ad group, clicks, cost, conversions; filters for min cost, min clicks, zero conversions |
| Keywords with quality score (and its components) plus performance metrics |
| Ads with type, status, approval status, ad strength, final URL, headlines/descriptions, plus performance metrics |
| Conversions per conversion action (calls, forms, ...) per campaign, with cost per conversion for each: true cost per lead |
| Who changed what and when (last 30 days max), with old and new values for each changed field |
| Finds campaigns by name (case-insensitive regex, e.g. |
Details:
Dates: the report tools take either
date_range(a GAQL preset such asLAST_7_DAYS,LAST_30_DAYS,THIS_MONTH,LAST_MONTH; defaultLAST_30_DAYS) orstart_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_gaqlreturns raw API values, so_microsfields stay in micros.Row cap: results are capped at
limitrows (default 100, max 1000). Output includestruncated: trueand a note when there were more.API version: the server uses Google Ads API v26, set by
GOOGLE_ADS_API_VERSIONin 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), plusGET /healthzfor health checks.Every
/mcprequest must carryAuthorization: Bearer <MCP_AUTH_TOKEN>. The server refuses to start ifMCP_AUTH_TOKENis 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-idset to the MCC ID, plus thedeveloper-tokenheader 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 |
| yes | OAuth client ID (Desktop app type) |
| yes | OAuth client secret |
| yes | From |
| yes | Your MCC customer ID, e.g. |
| no | Optional. Sent if set, but ignored by Google since September 9, 2026 |
| yes | Long random string Claude must send as a Bearer token |
| 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.
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:
adwordsis a sensitive scope, so it changes that project's verification status and can trigger Google's "This app is blocked" screen.
Enable the API (APIs & Services > Library): search for Google Ads API and click Enable. The project now has Test access.
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.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
Google Auth Platform > Clients > Create client.
Application type: Desktop app. Give it a name and click Create.
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 installThen 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-authmacOS / Linux:
GOOGLE_ADS_CLIENT_ID="your-client-id.apps.googleusercontent.com" GOOGLE_ADS_CLIENT_SECRET="your-client-secret" npm run setup-authThe script:
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.
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.
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 thecodevalue) and paste it into the terminal.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
In Railway, click New Project > Deploy from GitHub repo and pick
google-ads-mcp-server. Railway finds theDockerfileand builds with it.Open the service > Variables and add
GOOGLE_ADS_CLIENT_ID,GOOGLE_ADS_CLIENT_SECRET,GOOGLE_ADS_REFRESH_TOKEN,GOOGLE_ADS_LOGIN_CUSTOMER_IDandMCP_AUTH_TOKEN. Don't setPORT; Railway provides it.Settings > Networking > Generate Domain to get a public URL like
https://google-ads-mcp-server-production.up.railway.app.Optional: Settings > Deploy > Healthcheck Path =
/healthz.Check it: opening
https://<your-domain>/healthzshould show{"status":"ok"}, and the deploy logs should saygoogle-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:
Go to Organization settings > Connectors, select Add, then Custom (choose Web if asked).
Name: e.g. "Google Ads". MCP server URL:
https://<your-domain>/mcp.Authentication: No sign-in.
Request headers: header name
authorization, valueBearer <your MCP_AUTH_TOKEN>. Type the wordBearer, a space, then the token; Claude sends the value exactly as entered. Mark it Required.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 devnpm 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 |
| The Cloud project that owns the OAuth client needs Explorer or Basic access (step 1.3). |
| Known Google issue for projects upgraded after September 9, 2026; Google says a fix is rolling out. Otherwise check MCC access. |
| Remove |
| The account isn't linked under |
| Check field names (snake_case), field/resource compatibility, and quoting. The Query Builder helps. |
| Enable Google Ads API in the same Cloud project as the OAuth client. |
"This app is blocked" during | The consent screen is External and unverified, and |
| Refresh token revoked or expired (7-day expiry if the consent screen is External + Testing). Re-run |
| The API version may be sunset. Bump |
| The connector isn't sending |
Server exits at startup | Read the deploy log: it names the missing variable. |
Security notes
Never commit
.env, OAuth client JSON or tokens..gitignoreand.dockerignoreblock 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_TOKENand 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Ask Claude about your Google Ads: campaign performance, wasted search terms, GAQL reports.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Read-only Google Ads for Claude: finds search terms that spend without converting.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to access and manage Google Ads data, including campaigns, ad groups, keywords, budgets, and visualizations, through natural language interactions.19-
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityDmaintenanceConnects Claude Desktop to your Google Ads account, allowing you to analyze and manage campaigns, ad groups, and keywords using natural language.MIT
- AlicenseNot gradedqualityCmaintenanceEnables natural-language analysis and management of Google Ads accounts, campaigns, keywords, budgets, and performance metrics through Claude.MIT