Google Ads MCP Server: Connect Claude and Lock Down Access

Set up Google's official MCP server so Claude can query your Google Ads account, then sign it in as a Read only user so its credentials can't edit campaigns.

The Google Ads MCP server is Google’s open-source program that lets an AI assistant such as Claude query your ad account through the Google Ads API. The current release is read-only and has three tools. To connect it, you need a Google Cloud project with at least Explorer access, OAuth credentials and one configuration block in your assistant. Lock down access first: sign in through a separate Google account with the Read only role, because the API uses the same permission for reading and writing.

An assistant connected through MCP is one of several ways to let software work in your ad account. The others are automated rules, scripts and the API itself. Our guide to Google Ads automation compares them. This article covers the official server, the two kinds of access level that limit it, setup in Claude Desktop and Claude Code, and the limits you hit in the first week.

What the official server can and can’t do

Model Context Protocol is an open-source standard for connecting AI applications to external systems, according to the MCP documentation. An MCP server is the program on the other side of that connection. It offers tools. The model behind the assistant decides when to call them, and the results go into the model’s context window.

Google’s server sits between the assistant and the Google Ads API. Its developer integration guide describes it as a Python program that runs on your computer, or on Cloud Run as a web service. It signs in with OAuth 2.0 or a service account. The current release is read-only: “It cannot modify bids, pause campaigns, or create new assets.” The code is open on GitHub under the Apache 2.0 licence.

Tool	What it does	What you use it for
`list_accessible_customers`	Returns the IDs of accounts the signed-in user can reach directly	Checking that the assistant sees only the accounts you meant
`get_resource_metadata`	Describes a resource type, such as `campaign`: which fields you can select and filter on	Stopping the model from guessing field names
`search`	Builds a query from fields, a resource, conditions, ordering and an optional row limit, then returns the rows	Every report: campaigns, products, search terms, change history

The search tool writes the GAQL query itself, and the query always starts with SELECT. The server stays read-only because every tool calls only read methods of the API: none of them sends a change. It also offers four reference resources: the API discovery document, the list of metrics, the list of segments and the latest release notes.

Two lines in the server’s README matter before you connect anything. Your account data goes to whichever assistant and model you connect to the server. And the server adds an extra header to API calls so Google can collect usage data.

Two kinds of access level decide what the assistant can reach

Google uses the words “access level” for two unrelated things. One limits what the signed-in user may do in an ad account. The other limits how many queries your Google Cloud project may run. You need to get both right.

User access levels: what the signed-in user may change

The Google Ads API borrows its access model from Google Ads. According to Understand the Google Ads access model, the API uses the same OAuth scopes for read-only and read-write operations. It follows the user roles that Google Ads supports. The server’s own code says the same: Google publishes no separate read-only scope, so the read-only limit comes from the tools the server offers.

The consequence: the official server won’t write, but the credentials you create for it can, in any other tool that reuses them. The limit on changes that Google itself enforces is the role of the signed-in user. The API recognises four user access levels, or roles, listed in the AccessRole reference:

Role	What it allows
Admin	Owns the account and controls who else is added
Standard	Can modify campaigns, but can’t affect other users
Read only	Can view campaigns and account changes, but can’t make edits
Email only	An email recipient rather than a real user

Roles granted on a manager account pass down to every account linked under it. Say you connect with a Google account that holds Standard or Admin access on an agency’s manager account. The assistant then reaches every client account under it with that role.

API access levels: how many queries your Cloud project may run

Google retired developer tokens on 9 September 2026, according to its Developer token page. API access levels now belong to the Google Cloud project that owns your OAuth client or service account. If a request still carries a developer token, the API ignores it.

The repository README still describes a developer token step and marks it optional. Google’s integration guide says the latest version of the server no longer needs one.

The limits for each level, from Google’s Access levels and permissible use page:

API access level	Accounts it can query	Operations per day
Test	Test accounts only	15,000
Explorer	Test and production accounts	2,880 on production accounts, 15,000 on test accounts
Basic	Test and production accounts	15,000
Standard	Test and production accounts	Unlimited

Explorer is the lowest level that can query a production account, the kind that serves real ads. You apply for it on the Google Ads API Overview page in Google Cloud Console, and Google may upgrade the project automatically. Before you apply for Basic, your Cloud project needs brand verification.

Each Search or SearchStream request counts as one operation, however many rows it returns (API limits and quotas). Google counts a day as the last 24 hours at any moment. So 2,880 operations a day come to two a minute, around the clock.

That is plenty for a person asking questions. An assistant that runs a separate query for every campaign or every day can use it up.

How to connect Claude to Google Ads, step by step

These steps put the lock first, so the credentials never belong to a Google account with admin rights.

Create the Google account the assistant will act as. Use a separate address, for example reports@your-domain. Ask an account admin to give it the Read only role in Google Ads (how to grant the role). Check: the new account has accepted the invitation, and the user list shows Read only next to its address.
Set up the Google Cloud project. Enable the Google Ads API in it, open the Google Ads API Overview page and apply for Explorer if the project still shows Test. Check: the page shows Explorer, Basic or Standard.
Create OAuth credentials and sign in as the Read only account. Create a desktop or web OAuth client, download its JSON file, then run the command from the README. When the browser opens, choose the Read only account, not your own admin account.
```
gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE
```
Check: the command prints the path where it saved the credentials file. Treat that file like a password: whoever holds it acts as that user.
Install pipx and add the server to your assistant. This is the block from Google’s integration guide:
```
{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}
```
- Claude Desktop: open Settings from the Claude menu, go to Developer and select Edit Config. That opens claude_desktop_config.json. Paste the block, save, then quit and restart the app (Connect to local MCP servers).
- Claude Code: add the same server from the command line (Connect Claude Code to tools via MCP). Keep --transport stdio between the variables and the server name, or the CLI reads the name as one more variable.
```
claude mcp add --env GOOGLE_PROJECT_ID=YOUR_PROJECT_ID GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json \
  --transport stdio google-ads-mcp \
  -- pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp
```
If you reach the account through a manager account, add GOOGLE_ADS_LOGIN_CUSTOMER_ID with the manager’s ID. According to the README, the same mcpServers block works in Cursor and VS Code.
Run the first check. Ask: “What customers do I have access to?” Check: the answer is a list of account IDs. If you see the error CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION, the project is still at Test access.

What to lock down before the first real prompt

Lock	Why
A separate Google account with the Read only role	The API follows user roles, and that role is the limit on changes Google enforces
Access to one ad account directly, not through a manager account	Roles on a manager account pass down to every linked account
Credentials outside any shared configuration	In Claude Code, `--scope project` writes the server into `.mcp.json`, a file meant to be shared through version control. The default local scope keeps it in `~/.claude.json`
The server as a separate process, if several tools share it	The README says that a server the assistant starts itself keeps the credentials less isolated, because the path to them sits in the assistant’s configuration. If you run the server as a local web service, make it listen on the loopback address only
Only the tools you need	`tools_config.yaml` switches individual tools and groups of tools on or off
A record of what was asked	The server logs every query the `search` tool builds. Claude Desktop writes a local server’s stderr output to `mcp-server-<name>.log`, in `~/Library/Logs/Claude` on macOS
A person between the model and any change	The MCP specification says a human should always be able to deny tool calls. It also tells the assistant to treat a tool’s “read-only” label as untrusted unless the server is trusted
Caution with outside text	Account data includes text that people outside your company wrote, such as search terms. Prompt injection hides instructions in text like that. With read-only tools, the damage is a wrong answer. With write tools, it is a change in the account
A test account before any server that writes	Test accounts don’t serve ads and need their own test manager account. They have no performance data, so for the read-only server they only prove the connection works

Two of these locks matter most once you add a third-party server with write tools: caution with outside text and a test account. Our article on AI agents that change your account covers the guardrails for that case.

The limits you hit in the first week

Answers that don’t fit. The search tool returns every row unless the model sets a limit. Claude Code warns when a tool’s output passes 10,000 tokens. Above 25,000 tokens, by default, it saves the result to a file and gives Claude the path instead.

Example store, not client data.

A tableware shop has 3,000 products, and 1,200 of them got impressions this month. A report with one row per product per day for 30 days can return up to 36,000 rows. Against the 25,000-token limit, that leaves less than one token per row. Ask for totals by campaign, or the top 50 products by cost, rather than every row.

The quota. At Explorer, everything that uses the Cloud project, the assistant included, shares 2,880 operations a day.

Change history. The change_event resource covers only the last 30 days, and every query needs a LIMIT of 10,000 rows or fewer (Change Event). For each change, it shows the old and new values and whether the change came through the API or the web interface. It also names the user when Change History shows one.

Fields that mean something other than they seem. Three examples from Google’s field references for the API:

Money comes in micros: one million micros equal one unit of the account’s currency (campaign_budget reference).
metrics.all_conversions counts all conversions, including actions you left out of the Conversions column (metrics reference).
Search budget lost impression share stops at 0.9: the API reports anything above it as 0.9001.

Our article on AI for Google Ads analysis shows how a model misreads fields like these and gives prompts that keep it from inventing numbers. Our guide to GAQL for product reporting has ready queries for products in Shopping and Performance Max.

Read first, confirm every write: the rules in our MCP design brief

In April 2026 we drafted a design brief for our own Google Ads MCP server. It is an internal draft, not a description of a live product. Its rules carry over to any setup:

Reading comes first. The first phase is read-only, and writing is a separate later phase.
The free-form query tool accepts SELECT only. Raw GAQL can only read data.
Every write needs an explicit confirmation. The tools that set product labels and bids wait for a yes, and the bid tool shows the previous value before it applies the new one.
Structure changes go through a person. The tool produces a Google Ads Editor CSV that a person reviews and imports.
The design plans for big answers and the quota. Every tool gets a limit parameter, pagination and a summary mode. Caching and batched queries protect the daily quota.

The portal follows the reading side of these rules, with no server for you to run. You can sign in with a separate Google account that holds the Read only role, so the guarantee sits on Google’s side (how the portal reads your account).

The portal and a home-built connection differ in two ways: upkeep and history. An MCP connection is yours to build and maintain, and two years of a shop’s history don’t fit into a chat (the portal compared with ChatGPT). When you first connect, the portal asks Google for up to two years of product history. From then on, it keeps its own copy of the change records, which the API serves for only 30 days.

Want a guarantee, not a promise? Sign in with a Google account that holds the Read only role in your account. The portal fully inherits the permissions of whoever signed in, so it cannot change anything even in theory: Google rejects the attempt — the user lacks the permissions.

Sign in with Google Ads →

Three first prompts, and how to check the answers

“What customers do I have access to?” Compare the IDs with the account list in Google Ads. An extra ID means the Google account reaches more than you planned.
“Use get_resource_metadata for shopping_performance_view and list the fields for cost, clicks and conversion value.” The server’s own instructions tell the model to look fields up rather than guess. This prompt shows whether it does.
“Show cost, clicks and conversion value by campaign for last month, top 20 by cost.” Open the Campaigns view in Google Ads for the same dates and compare the totals. If they differ, check the dates first, then micros, then whether the model used all_conversions.

Use the assistant’s numbers in a decision once all three answers match what you see in Google Ads.

Frequently asked questions

Can the Google Ads MCP server change my campaigns?

No. Google describes the current release as read-only, and its tools call only read methods of the API. Other MCP servers for Google Ads can include write tools. Check their tool list and treat their own “read-only” labels as claims, not guarantees.

Does it work with assistants other than Claude?

Yes, with any assistant that supports MCP. The README gives setups for Google’s Antigravity, OpenAI’s Codex, Claude Code, Cursor and VS Code.

Do I still need a developer token?

No. Since 9 September 2026, the API access level belongs to the Google Cloud project. If a request still carries a developer token, the API ignores it.

Sources

Google Ads MCP server: Developer integration guide — read-only current release, Python, stdio or Cloud Run, OAuth 2.0 or service account, three tools, developer token no longer required, configuration block. Checked 2 October 2026.
googleads/google-ads-mcp on GitHub — tools and resources, data exposure and usage-header notes, tools_config.yaml, credential isolation, Claude Code and other clients, gcloud command; source code of the search tool. Checked 2 October 2026.
Understand the Google Ads access model — same OAuth scopes for read-only and read-write operations; the API follows Google Ads user roles; roles pass down through manager accounts. Checked 2 October 2026.
AccessRole — what Admin, Standard, Read only and Email only allow. Checked 2 October 2026.
Developer token — developer tokens sunset on 9 September 2026; access levels belong to the Cloud project; brand verification for Basic; the Test access error. Checked 2 October 2026.
Access levels and permissible use — Test, Explorer, Basic and Standard limits; how to apply for Explorer; the sliding 24-hour day. Checked 2 October 2026.
API limits and quotas — one Search or SearchStream request counts as one operation. Checked 2 October 2026.
Test accounts — test accounts don’t serve ads and need a separate test manager hierarchy. Checked 2 October 2026.
Change Event — 30-day window, LIMIT of 10,000 rows, old and new values, user and client type. Checked 2 October 2026.
Metrics reference and campaign_budget reference — all_conversions, the 0.9 cap on search budget lost impression share, micros. Checked 2 October 2026.
What is the Model Context Protocol (MCP)? and Tools in the MCP specification — definition of MCP; a human in the loop; tool annotations are untrusted unless the server is trusted. Checked 2 October 2026.
Connect to local MCP servers — Claude Desktop configuration file and server log files. Checked 2 October 2026.
Connect Claude Code to tools via MCP and Claude Code security — claude mcp add, installation scopes, the 10,000 and 25,000-token output limits, prompt injection. Checked 2 October 2026.
GetProfit MCP server design brief, April 2026 (internal draft) — read-only first, SELECT-only raw queries, confirmed writes, Editor CSV for structure, limits and pagination.