MCP for Google Ads API
A privately deployed Model Context Protocol server that lets an AI agent operate the Google Ads API behind a human-confirmation gate.
mutations
endpoints
tenant
v24
What it is
The Caveman AIQ MCP for Google Ads is a productivity tool for advertising operators, delivered as a purpose-built MCP server that sits between an AI agent and the Google Ads API. It exposes the full set of read and write operations as MCP tools, stages every intended change for operator review, and only lets the agent reach the live account through explicit confirmation.
It is built and operated by Alexandros Mimilidis (Caveman AIQ), an independent technical consultant based in Athens, Greece, for the purpose of managing Google Ads for client accounts.
Every change is staged, reviewed, then applied.
The Google Ads API doesn't distinguish a deliberate operator decision from a misfired tool call. The MCP server enforces that distinction by design.
Confirmed in person
No mutation runs without an explicit confirmation.
Validated first
Every confirmed change runs through the API in validate-only mode. A rejected validation skips the real application.
Audited end-to-end
Every action is captured in a redacted local log, retrievable for investigation at any time.
How everything fits
Everything except the Google Ads API and the advertiser account runs on the operator's machine. The MCP server is the only outbound caller. The operator can also read the audit log directly to review activity.
The server is composed of four subsystems:
MCP Server
Handles incoming MCP tool calls and orchestrates the draft, confirm, validate, and apply flow.
ChangePlan store
In-memory, TTL-bounded record of an intended mutation, held between draft and confirm.
Retry classifier
Categorises every Google Ads API error and applies exponential backoff. All outbound calls pass through it.
Audit log
Append-only JSONL written for every tool call, retry, and outcome — redacted of customer data.
flowchart TB
subgraph local["Operator's machine (local)"]
direction TB
Operator["Operator + MCP host"]
Server["MCP Server"]
Plan[("ChangePlan store")]
Retry["Retry classifier"]
Log[("Audit log")]
end
subgraph google["Google (cloud)"]
direction TB
API["Google Ads API"]
Acct[("Client account")]
end
Operator <--> Server
Server <--> Plan
Server --> Retry
Server --> Log
Retry <--> API
API <--> Acct
classDef localNode fill:#FBF6F0,stroke:#7A6450,stroke-width:1.5px,color:#1F1812
classDef mcp fill:#F2E8DA,stroke:#8B4513,stroke-width:1.8px,color:#1F1812
classDef hub fill:#FFFFFF,stroke:#B05C3A,stroke-width:3px,color:#1F1812,font-weight:bold
classDef googleNode fill:#E5F2EB,stroke:#2E5C3E,stroke-width:1.5px,color:#1F1812
class Operator localNode
class Server hub
class Plan,Retry,Log mcp
class API,Acct googleNode
What is gated, what is not
Reads return data and pass through without a confirmation step. Writes always go through the staging + confirm + validate sequence.
Reporting and discovery
- Campaign, ad group, keyword, and search-term performance
- Recommendation retrieval
- Keyword discovery and volume estimates
- Conversion-action and audit-trail reads
Mutations on the client account
- Pause / enable / update on campaigns, ad groups, and ads
- Budget changes
- Keyword and negative-keyword changes
- Asset creation and attachment
| Google Ads API service | Used for | Gate |
|---|---|---|
GoogleAdsService | GAQL reads: performance, change-event tracking | Read |
KeywordPlanIdeaService | Keyword discovery, volume estimates, CPC ranges | Read |
RecommendationService | Google's automated account recommendations | Read |
ConversionActionService | Conversion action configuration and tracking health | Read |
CampaignService | Pause, enable, or update campaign-level settings | Write |
CampaignBudgetService | Update daily or shared budgets | Write |
AdGroupService | Pause, enable, or update ad groups | Write |
AdGroupAdService | Add or update responsive search ads | Write |
AdGroupCriterionService | Add, pause, or remove keywords at ad-group level | Write |
CampaignCriterionService | Add or remove campaign-level negative keywords | Write |
SharedSetService · SharedCriterionService | Manage shared negative-keyword lists | Write |
AssetService · CampaignAssetService · AdGroupAssetService | Create and attach sitelinks, callouts, structured snippets, image assets | Write |
One direction. Every write.
The same path runs for every mutation, from a one-keyword pause to a multi-asset launch.
flowchart TB
subgraph local["Operator's machine (local)"]
direction TB
A["Draft change"]
B["Stage as plan"]
C{"Operator
confirms?"}
X["Plan discarded"]
Y["Apply aborted"]
end
subgraph google["Google (cloud)"]
direction TB
D["Validate against API"]
E{"Validation
passes?"}
F["Apply to client account"]
end
A --> B
B --> C
C -->|"yes"| D
C -->|"no / expired"| X
D --> E
E -->|"pass"| F
E -->|"fail"| Y
classDef step fill:#FFFFFF,stroke:#5A4838,stroke-width:2px,color:#1F1812
classDef gate fill:#FBE7D4,stroke:#8C4A14,stroke-width:3px,color:#1F1812
classDef ok fill:#2C1F14,stroke:#C06A3E,stroke-width:2px,color:#FBF6F0
classDef stop fill:#F2E8DA,stroke:#8A7560,stroke-width:1.5px,color:#5A4838
class A,B,D step
class C,E gate
class F ok
class X,Y stop
An internal tool, not a product
Manages Google Ads for client accounts. Not licensed, not distributed.
Configured for one operator
One user, one configuration. No multi-user support, no shared infrastructure.
No network surface
Speaks to its MCP host over stdio. No TCP listener, no HTTP server, no inbound network.
Questions or engagements
Independent technical consultant, Athens, Greece. Available for similar agent-tooling, advertising automation, and analytics engagements.