Get Started with Google Ads MCP (2026)

Q: Which Google Ads MCP repo should I use?

Use `googleads/google-ads-mcp`. The older `google-marketing-solutions` repository has been archived in favour of it, so guides pointing there are out of date.

Last Updated: Sep 21, 2026

How to Set Up a Google Ads MCP Server (Claude, Cursor and Gemini CLI)

Quick answer: There are two ways to connect Google Ads to an AI assistant. Google’s official MCP server is free, open source and strictly read-only, and you run it yourself with a Google Cloud project, a developer token and OAuth credentials. Expect about an hour of setup plus developer token approval time. A hosted server removes all of that: sign in with OAuth, install an extension and start asking questions in about five minutes. Both read live campaign data. Neither changes your account unless you choose a write-capable server and approve each change.

Key takeaways

Google’s official server exposes exactly three tools: list_accessible_customers, search (GAQL) and get_resource_metadata (Google Ads API docs).
It is strictly read-only. Google’s docs state it “cannot modify bids, pause campaigns, or create new assets.”
Google announced the open-source server on 7 October 2025, for “reporting and diagnostics” (Google Ads Developer Blog).
The real delay is the developer token, not the install.
Any MCP server exposes the data it can read to the model you connect it to. Google’s repo says so directly, so treat it as a data-sharing decision.
Check every number before you act on it. Ask the assistant to show the GAQL query it ran.

What a Google Ads MCP server actually does

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to outside data and tools. A Google Ads MCP server sits between your assistant and the Google Ads API. You ask a question in plain English, the server turns it into a GAQL query, and the assistant answers from your live account data.

Google’s official server exposes three tools, and everything you ask flows through them:

Tool	What it does	What it can’t do
`list_accessible_customers`	Returns the customer IDs you can access	–
`search`	Runs a GAQL query for metrics, budgets, status and other resources	Change anything
`get_resource_metadata`	Returns metadata about resource types and available fields	Change anything

There is no tool for changing bids, budgets or campaign status. That’s deliberate: the read-only boundary is the safety model.

Which repo is the right one? Use googleads/google-ads-mcp. An older google-marketing-solutions repo still appears in search results, but it has been archived in favour of the official one. If a guide points you at the archived repo, it’s out of date.

For the background on why Google made it read-only, see Does Google Ads Have an Official MCP?

Which setup path should you choose?

	Path A: Google’s official server	Path B: hosted server
Who runs it	You (local machine or Cloud Run)	The provider
Hands-on time	About an hour	About 5 minutes
Waiting time	Developer token approval, often a day or more	None
Needs	Google Cloud project, developer token, OAuth credentials, pipx/Python	A Google Ads login
Access	Read-only	Read-only, or approval-gated writes with some vendors
Cost	Free and open source (plus Cloud Run costs if deployed)	Free tiers are common; paid plans vary
Data path	Your infrastructure, your model	The vendor’s infrastructure, then your model
Maintenance	Yours	Theirs
Best for	Developers, analysts, strict security policies	Marketers and agencies who want answers today

Decision rule: if you need raw GAQL control or your security policy requires self-hosting, take Path A. If you want campaign analysis this afternoon, take Path B. Many teams do both: hosted for daily work, self-hosted for anything sensitive.

The wider landscape

Type	What it is	Trade-off
Google’s official server	Free, open source, read-only	You run and maintain it
Hosted read-only servers	Vendor-run, OAuth sign-in, analysis only	Convenience in exchange for a third party in the data path
Hosted read-write servers	Can create and change campaigns, usually creating them paused and asking for confirmation before anything goes live	Powerful, and higher risk if approvals are weak
Community forks	Varying quality, sometimes with write access	Check the code and the maintainer before connecting an ad account

Before you start: prerequisites

For Path A you’ll need all of these:

A Google Cloud project with the Google Ads API enabled, and the gcloud CLI installed and authenticated.
A Google Ads developer token from the API Center of a manager account. Google’s docs note the server works with Explorer, Basic or Standard access levels. Request this first, because approval isn’t instant.
OAuth 2.0 credentials (client ID and secret) or application default credentials.
pipx or Python on the machine running the server.
An MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, or the Gemini or Antigravity CLI.
Your manager account (MCC) ID if you’ll query accounts under it.

OAuth credentials or a service account?

	Use it when	Watch out for
OAuth / application default credentials	A person is running the analysis on their own machine	Refresh tokens are tied to the OAuth client that created them
Service account	A shared, always-on deployment	A service account has no Google Ads access by default, so it must be granted access explicitly

Path A: set up Google’s official server

Step 1: Get your developer token

In your Google Ads manager account, go to Tools → Setup → API Center and request a developer token. Note the access level you receive, because it limits which accounts you can query.

Step 2: Set up the Google Cloud project

Create or select a project, enable the Google Ads API, then authenticate:

Run these two commands, one after the other:

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

Step 3: Create OAuth credentials

In the Cloud console, under APIs & Services → Credentials, create an OAuth 2.0 client ID (a desktop app type works for local use) and save the client ID and secret.

Step 4: Add the server to your MCP client

Add this to your client’s MCP config file, for example settings.json for Claude Code or mcp.json for Cursor:

The entry has four parts:

Field	Value to use
Server name	`google-ads-mcp`
`command`	`pipx`
`args`	`run`, `--spec`, `git+https://github.com/googleads/google-ads-mcp.git`, `google-ads-mcp`
`env`	`GOOGLE_APPLICATION_CREDENTIALS` (path to your credentials JSON), `GOOGLE_PROJECT_ID` (your project ID), `GOOGLE_ADS_DEVELOPER_TOKEN` (your token)

Here is the same entry as a single line you can paste and then reformat:

{"mcpServers":{"google-ads-mcp":{"command":"pipx","args":["run","--spec","git+https://github.com/googleads/google-ads-mcp.git","google-ads-mcp"],"env":{"GOOGLE_APPLICATION_CREDENTIALS":"PATH_TO_CREDENTIALS_JSON","GOOGLE_PROJECT_ID":"YOUR_PROJECT_ID","GOOGLE_ADS_DEVELOPER_TOKEN":"YOUR_DEVELOPER_TOKEN"}}}}

Environment variables you may also need:

Variable	When you need it
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	Querying accounts through a manager account
`GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` / `_SECRET`	Running in OAuth proxy mode
`GOOGLE_ADS_MCP_BASE_URL`	OAuth proxy mode, pointing at your server URL
`GOOGLE_ADS_MCP_STORAGE_TYPE`	Choosing where tokens are stored

Source: the googleads/google-ads-mcp repository. Check it for current syntax, since the project is actively developed.

Step 5 (optional): Deploy to Cloud Run

Hosting the server on Cloud Run gives it a URL your team and agents can share:

Deploy with: gcloud run deploy google-ads-mcp --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest --platform managed --region us-central1

Then point your client at the deployed URL instead of running it locally.

Step 6: Restart and verify

Restart the client, then ask: “List the Google Ads accounts I can access.” Customer IDs coming back means the connection works.

Cloud Run deployment: the traps worth knowing

Local setup is straightforward. Cloud Run is where people lose an afternoon. The common failures, drawn from one engineer’s write-up of deploying it:

Trap	What happens	Fix
Using SSE transport	Persistent connections don’t suit Cloud Run’s stateless, autoscaling model	Use streamable HTTP from the start
Service account has no Ads access	Authentication succeeds, but every Google Ads query fails	Grant the account access explicitly, or use OAuth credentials
Refresh token mismatch	A token generated by a different OAuth client silently fails	Generate the refresh token with your own client ID and secret
Invisible whitespace in secrets	Credentials look identical but authentication fails	Use `printf` rather than `echo` when writing secrets
`421 Invalid Host header`	DNS rebinding protection rejects requests	Configure the allowed hosts for your deployment
Missing env vars on the service	Works locally, fails once deployed	Set the same variables on the Cloud Run service

If you only need analysis for yourself, run the server locally and skip this entirely.

Path B: the hosted route (about 5 minutes)

Register for a hosted Google Ads MCP, such as GrowthSpree’s free Google Ads MCP.
Authorize Google Ads with read-only OAuth. Optionally connect your CRM, also read-only, so the assistant can see pipeline and not just clicks.
Copy your MCP token from the dashboard.
Install Claude Desktop, then drag the provided .mcpb extension file into Settings → Extensions.
Paste your token, switch the extension on, open a new chat and start asking.

No developer token, no Cloud project, no Python.

Connecting different AI clients

Client	Where the config lives	Notes
Claude Desktop	Settings → Extensions (hosted) or the MCP config file (self-hosted)	Easiest route for marketers
Claude Code	`settings.json`	Good for repeatable audits and scripted analysis
Cursor	`mcp.json`	Convenient if you already work there
VS Code	MCP settings file	Same JSON shape
Gemini / Antigravity CLI	`httpUrl`, for example `http://localhost:8080/mcp`	Use with the HTTP/OAuth mode

MCP is assistant-agnostic, so the same server works across clients. Only the config file changes.

Your first 15 minutes after connecting

Confirm the account. “Which customer ID are you querying?”
Check the totals. “Show spend and conversions for the last 30 days.” Compare that with the Google Ads interface. If they don’t match, stop and fix the connection before going further.
Look at the query. “Show me the GAQL you used.” This is the habit that protects you from confident, wrong answers.
Run one real question. “Which campaigns spent the most last week with the fewest conversions?”
Save what works. Keep your best prompts in a doc so the whole team runs the same checks.

Troubleshooting the common failures

Symptom	Likely cause	Fix
No tools appear in the client	The server failed to start	Check the client’s MCP logs, confirm pipx runs the package, look for typos in env vars and paths
`DEVELOPER_TOKEN_NOT_APPROVED`	Token’s access level doesn’t cover the account	Request a higher access level in the API Center
`AUTHENTICATION_ERROR`	Expired or mismatched credentials	Re-run `gcloud auth application-default login`, or regenerate the refresh token with your own OAuth client
`USER_PERMISSION_DENIED`	The authenticated user can’t see that account	Check account access and set `GOOGLE_ADS_LOGIN_CUSTOMER_ID` for MCC queries
`RESOURCE_EXHAUSTED`	API rate limits	Narrow the date range, ask for fewer rows, and space out large pulls
Costs look a million times too big	Google Ads returns money in micros	Divide by 1,000,000, and tell the assistant to do the same
Empty results for a fair question	Wrong resource or date range in the query	Ask for the GAQL and correct it
Numbers don’t match the Google Ads interface	Different date range, time zone, attribution window or segment	Pin the date range and time zone in the prompt, and compare like with like
Works locally, fails on Cloud Run	Missing env vars, service account access or transport settings	See the Cloud Run table above

Read-only vs read-write, and staying safe

Google’s official server is read-only, and most hosted analytics servers are too. Some vendors offer write access, typically creating new campaigns paused and requiring explicit confirmation before anything live is changed.

Three rules worth keeping:

Use read-only for analysis. Reporting, diagnostics and audits are most of the value.
Require human approval for anything touching live budget.
Keep one connection per account, so access can be revoked cleanly.

A data note: Google’s repository warns that the MCP server “will expose your data to the Agent or LLM that you connect to it.” Read your provider’s policy on whether your data is used for training, use read-only scopes, and revoke access when you’re done.

Accuracy guardrails

AI assistants can produce a confident answer from a slightly wrong query. Four habits catch most of it:

Pin the date range and time zone in the prompt.
Ask for the GAQL behind any number you plan to act on.
Spot-check one figure against the Google Ads interface each session.
Remember conversion lag. Recent days will under-report, especially with long B2B sales cycles.

What to ask once it’s connected

Tier 1: triage (daily or weekly)

“Which campaigns spent the most last week with the fewest conversions?”
“Show spend, conversions and cost per conversion by campaign for the last 14 days versus the previous 14.”
“Which campaigns are limited by budget right now?”
“Flag any campaign where cost per conversion rose more than 30% week over week.”

Tier 2: diagnose (when something moves)

“CPA rose 40% over 10 days. Break it down by campaign, device and match type, and tell me what changed.”
“List search terms over $500 in the last 90 days with zero conversions.”
“Which keywords have Quality Score below 4 and more than $1,000 of spend?”
“Show impression share lost to budget and to rank for my top 10 converting campaigns.”
“Compare brand and non-brand performance over the last two quarters.”

Tier 3: decide (monthly or quarterly)

“Rank every campaign by cost per conversion and flag any above 3x the account average.”
“If I moved 20% of budget from the bottom five campaigns to the top three, what conversion change should I expect at current rates?”
“Build a negative keyword list from search terms with spend and no conversions in 90 days.”
“Write a one-page monthly summary for my CMO: spend, pipeline, efficiency and the three changes I’d make.”

For agencies: “For every account I can access, show spend versus budget pacing for this month and flag anything more than 10% off track.”

Connecting your CRM as well as Google Ads is what makes the third tier genuinely useful, because campaigns can then be judged on pipeline instead of form fills. Pair this with our Google Ads audit checklist and the negative keyword template.

A little GAQL goes a long way

You don’t need to write GAQL, but recognizing it helps you check the assistant’s work. A basic query looks like this:

SELECT campaign.name, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC

Three things to look for when you review one:

The resource after FROM (campaign, ad_group, keyword_view, search_term_view) decides what the numbers describe.
segments.date sets the date range. If it’s missing, the range may not be what you assumed.
cost_micros is in micros, so it needs dividing by 1,000,000.

Multi-account and agency setups

Connect through your manager account (MCC) for cross-account analysis, and set GOOGLE_ADS_LOGIN_CUSTOMER_ID to the MCC ID.
Ask the assistant to confirm the customer ID before you act on numbers.
For client work, keep one connection per client account so access is easy to revoke and audit.
An MCC gives access to accounts. MCP adds the natural-language layer on top.

Security checklist

OAuth scope is read-only
Developer token stored in environment variables or a secret manager, never in a shared doc or repo
Cloud Run service (if used) is not publicly reachable without authentication
You’ve read the provider’s policy on training and data retention
Access can be revoked quickly, and someone owns that
Any write-capable server requires approval before changes go live
Client accounts connected separately, not through one shared login

Honest limitations

The official server is read-only. It analyzes, it doesn’t act.
The developer token is the bottleneck. Plan for approval time before promising anyone a demo.
Answers are only as good as your tracking. Misconfigured conversions produce confident, wrong analysis.
Ad platform data isn’t pipeline data. Connect the CRM if you want answers about qualified pipeline.
Large pulls hit rate limits. Narrow date ranges and request fewer rows.
This ecosystem changes fast. Google’s docs and repository are the source of truth for current commands and tools.

Frequently Asked Questions

Q1. What is a Google Ads MCP server?

It’s a connector that lets an AI assistant read your Google Ads data through the Model Context Protocol. You ask in plain English, the server runs the matching GAQL query, and the assistant answers from your live account data.

Q2. Does Google have an official Google Ads MCP server?

Yes. Google announced an open-source server in October 2025. It exposes three tools, list_accessible_customers, search and get_resource_metadata, and is strictly read-only.

Q3. Which Google Ads MCP repo should I use?

Use googleads/google-ads-mcp. The older google-marketing-solutions repository has been archived in favour of it, so guides pointing there are out of date.

Q4. How do I set up Google Ads MCP without coding?

Use a hosted server: register, authorize Google Ads with read-only OAuth, copy your token, install the provider’s Claude Desktop extension, paste the token and start asking questions. About five minutes.

Q5. What do I need for the official server?

A Google Cloud project with the Google Ads API enabled, the gcloud CLI, a Google Ads developer token, OAuth credentials or application default credentials, and pipx or Python. Then add the server to your MCP client’s config.

Q6. Can a Google Ads MCP server change my campaigns?

Not Google’s official server, which cannot modify bids, pause campaigns or create assets. Some third-party servers add write access, usually creating campaigns paused and asking for confirmation before live changes.

Q7. Why don’t my tools show up in Claude or Cursor?

Almost always a server that failed to start. Check the client’s MCP logs, confirm pipx can run the package, and look for typos in the environment variables or config path.

Q8. What does DEVELOPER_TOKEN_NOT_APPROVED mean?

Your developer token’s access level doesn’t cover the account you’re querying. Request a higher access level in the Google Ads API Center.

Q9. Why are the cost numbers so large?

Google Ads returns money in micros, so 1,000,000 equals one unit of currency. Divide by 1,000,000 and ask the assistant to do the same in its answers.

Q10. Why don’t the numbers match the Google Ads interface?

Usually a different date range, time zone, attribution setting or segment, or conversion lag on recent days. Pin the date range and time zone in your prompt and compare like with like.

Q11. Does it work with multiple accounts?

Yes. Connect through your manager account (MCC) and set the login customer ID. You can then run cross-account analysis in one conversation.

Q12. Which AI assistants work with it?

MCP is assistant-agnostic. Claude Desktop, Claude Code, Cursor, VS Code and the Gemini and Antigravity CLIs all support MCP servers. Hosted options aimed at marketers usually target Claude Desktop.

Q13. Is it secure?

Access uses OAuth and the official server is read-only. Note that any MCP server exposes the data it reads to the model you connect it to, so check your provider’s data policy and revoke access when finished.

Q14. How long does setup take?

A hosted server takes about five minutes. The official server takes roughly an hour of hands-on work, plus developer token approval time.

Get your Google Ads data into AI today

Want the analysis without the setup? Connect GrowthSpree’s free, read-only Google Ads MCP and start asking where your budget is going. If you’d like us to run the analysis with you, book a 30-minute call.

Book your free call →