Open source

A Google Ads MCP server you can host yourself

42 tools that let ChatGPT or Claude run your Google Ads accounts — read performance, research keywords, build campaigns, change budgets — behind guardrails the model cannot talk its way past.

New to this? Our explainer covers what a Google Ads MCP server is, what it can expose, and what to check before trusting one. Read the MCP server explainer

• 42 tools
• MIT licence
• Java 21 · Spring Boot

Why this is harder than it looks

Developer tokens start restricted

A new Google Ads developer token has Test Account access and can only reach test accounts. Your first correct run returns empty lists and looks broken. Basic access needs an application, and approval takes days — so start there.

Manager accounts hold no campaigns

Google mostly returns manager (MCC) accounts, which cannot run ads. The accounts that can are their children, and each one has to be addressed with the manager it was found under.

The API speaks micros

Amounts arrive in millionths. A budget of 5000000 is five units of currency, and getting the factor wrong by a million is not a rounding error — it is a spend incident.

Amounts carry no currency

Nothing in a response says which currency a number is in. Report a budget from a UAH account with a dollar sign and the reader sees roughly forty times the real figure.

GAQL is not SQL

There are no joins, and segmentation changes what a row means rather than only how many there are. Ask for the wrong segment and your totals quietly multiply.

Versions are retired, not deprecated

Google switches old API versions off on a published schedule. A pinned version stops working on a date, so the version has to be configurable without waiting for a release.

What it will not do

Worth reading before the install command, because a mistake here spends real money.

• Nothing goes live by itself. Campaign creation has no status field in its tool schema, so a model cannot create an enabled campaign even if it tries.
• Only campaigns this server created can be activated through it. One made in the Google Ads interface is refused, because its budget never passed the cap check.
• Every budget change is checked against a cap you set, in the ad account's own currency. The server refuses the change; it never quietly lowers it to fit.
• Each write tool has a daily limit, so a model stuck in a loop cannot make hundreds of changes to one account.
• A separate runaway guard refuses a burst of calls in a short window, whatever the tool.
• It authenticates one operator by default: a single password and a single account, not a multi-user login you have to secure.

How it fits together

mcp-core

The protocol layer and a small OAuth 2.1 authorization server: dynamic client registration, PKCE, refresh-token rotation with reuse detection, and a consent screen. Knows nothing about advertising, so it works for any tools you want an assistant to call.

google-ads client

A plain Google Ads API client with no Spring and no MCP. Usable on its own by anything that needs to talk to Google Ads, which is why it ships as its own artifact.

google-ads server

The runnable server: the 42 tools, the spend guardrails, the audit trail of every write, and the flow that connects a Google Ads account.

The 42 tools

Read tools need read access; write tools need write access and pass the guardrails above.

• Accounts, billing and pacing — List reachable accounts, check billing setup, and see today's spend against each campaign's budget.
• Campaigns — List, create as paused, activate, pause, resume, and change budgets, bidding, settings, targeting, negatives and conversion goals.
• Ad groups and ads — Create and edit ad groups, list individual ads with their policy verdicts, and create or update responsive search ads.
• Keywords and search terms — List, add, remove and edit keywords, read the queries people actually typed, and pull keyword ideas.
• Performance Max — Read and edit asset groups, their assets and media, search themes, and campaign-level brand assets.
• Sitelinks — List, create, update and remove sitelink assets at campaign level.
• Insights — Performance by account, campaign, ad group or keyword, plus geography, audience and conversion actions.

Run it yourself

The published image needs no Java and no build. Copy the example environment file, fill it in, and start it — every value is documented where you set it.

# 1. the compose file and the documented environment template
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/.env.example

# 2. fill it in — every value says what it is and how to generate it
cp .env.example .env

# 3. start it; the image is prebuilt, so there is no JDK and no Maven here
docker compose up

curl -s -X POST https://your-host/mcp \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

One prerequisite is slow rather than hard: the Google Ads developer token needs an application to Google and approval takes days. Start that before anything else.

Questions