Open source

A Google Ads MCP server you can host yourself

43 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.

View on GitHubRun itdocker compose up

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

43 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.
A campaign cannot be deleted while it is running. Removal refuses anything that is not already paused, and the caller has to echo the campaign's exact name back, so a wrong id fails loudly instead of destroying the wrong campaign. Removal is permanent: Google offers no way back through the API.
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 43 tools, the spend guardrails, the audit trail of every write, and the flow that connects a Google Ads account.

The 43 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, remove for good, 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.

ghcr.io/loomascale/google-ads-mcp

# 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

tools/list

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.

Or skip the setup

LoomaScale is a managed MCP server for the same ad accounts, built on the same tools. No developer token application, no OAuth client to register, no server to keep running. It begins with a free audit that reads your account and reports what is being wasted, before you pay anything. Self-hosting is a real alternative rather than a teaser: nothing is held back from the repository, and the server never reports home.

Installing it is one click from the assistant's own directory: see how to connect Claude to Google Ads, or the ChatGPT setup guide.

Get the free audit See plans

Questions

Can the assistant spend money without asking me?

It cannot make a campaign live on its own: the creation tool has no status field, so an enabled campaign is not something it can express. Activating one is a separate tool that only works on campaigns this server created, and every budget change is checked against a cap you set and refused if it exceeds it.

Can it delete a campaign?

Yes, but only a campaign that is already paused, and only when the exact campaign name is echoed back as confirmation. A running campaign is refused until you pause it. Removal is permanent: the Google Ads API offers no way back, so pausing is the reversible choice.

Does it work with both ChatGPT and Claude?

Yes. Both register themselves with the server over standard OAuth, so there is no key to paste. They do need a public HTTPS address, so for local testing use a tunnel rather than pointing them at localhost.

Do I need a Google Ads manager account?

You need one to apply for the developer token. You do not need to configure anything else: the connect flow walks the accounts your login can reach, skips the manager accounts that cannot run ads, and records how to address each remaining account.

What does it store?

Your Google credentials, encrypted at rest, and an audit record of every write it made. Campaign data stays in Google Ads and is read on demand rather than copied.

Is the self-hosted version missing features?

No. The tools and the guardrails here are the ones extracted from the product, not a reduced set. What the hosted version adds is the commercial half — accounts, billing, usage limits and the dashboard — and in the open-source build those are replaceable interfaces rather than gaps.

Rather have it run for you?

The hosted version starts with a free audit of your Google Ads account.

See what it finds

Connect your assistant to your ad platform

LoomaScale runs inside the assistant you already use. Pick the pair you work with; each guide takes about five minutes.

Manage Google Ads campaigns from ChatGPT: search terms, budgets and new campaigns, paused for your review. One-click install from ChatGPT's directory.

Read the integration

Manage Google Ads from Claude: audits, budget changes and new campaigns, every write inside the spend cap you set. Connect from Claude's directory.

Read the integration

Install the LoomaScale plugin in Claude Code with two commands and audit Google Ads from your terminal: search terms, budgets and pacing, with skills built in.

Read the integration

Install the LoomaScale plugin in OpenAI Codex with two commands and audit Google Ads from your terminal: search terms, budgets and conversion goals.

Read the integration

Manage Facebook and Instagram campaigns from ChatGPT: ad sets, budgets and creatives in one chat. The same one-click install.

Read the integration

Manage Facebook and Instagram campaigns from Claude: audits, budget caps and new ad sets, inside the limits you set.

Read the integration

Run Facebook and Instagram campaign reviews from Claude Code: the same plugin, one sign-in, and skills for waste audits, pacing and creative fatigue.

Read the integration

Review Facebook and Instagram campaigns from OpenAI Codex: the same plugin and sign-in, with placement, age and lead-quality checks.

Read the integration

Connect Manus to Google Ads through LoomaScale’s MCP server. Analyze campaigns, keywords and search terms, then request changes within your permissions and spend cap.

Read the integration

Ask Slackbot about Google Ads in any Slack DM: audits, search terms and pacing checks, with changes kept inside your spend cap. Install the app once per workspace.

Read the integration

Connect Manus to Meta Ads through LoomaScale’s MCP server. Review Facebook and Instagram campaigns, ad sets, creatives and placements.

Read the integration

Ask Slackbot about Facebook and Instagram campaigns in any Slack DM: delivery, pacing and ad-set spend, read live from Meta Ads.

Read the integration