# connorcallison/google-ads-mcp architecture

> Architecture diagram of the GitHub repository connorcallison/google-ads-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/connorcallison/google-ads-mcp
- Repository: https://github.com/connorcallison/google-ads-mcp

## Overview

Google Ads MCP is a local, write-capable MCP server and helper CLI for operating Google Ads accounts through the official API. The principal workflow is an MCP client invoking a tool, the server resolving and validating account settings, the gateway querying or mutating Google Ads, and write requests being audited before and after the provider call. The gateway also supports separate reporting, geographic targeting, and keyword-planning stages. The README documents several capabilities whose implementation details were not sampled; those relationships are shown at the documented level, without inferring unshown internal calls.

Main entry points: [`src/google_ads_mcp/mcp_server.py`](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/mcp_server.py) (MCP tools), [`src/google_ads_mcp/google_ads.py`](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py) (Google Ads gateway), [`src/google_ads_mcp/cli.py`](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/cli.py) (Helper CLI), [`src/google_ads_mcp/audit.py`](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/audit.py) (Audit logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Operator interfaces"]
  node_mcp_server["MCP tools<br/>[mcp_server.py]"]
  node_helper_cli["Helper CLI<br/>[cli.py]"]
end

subgraph group_planning["Reporting and planning"]
  node_customer_access["Customer access<br/>[google_ads.py]"]
  node_gaql_search["GAQL reporting<br/>[google_ads.py]"]
  node_geo_targets["Geo targeting<br/>[google_ads.py]"]
  node_keyword_ideas["Keyword ideas<br/>[google_ads.py]"]
  node_keyword_forecast["Search forecast<br/>[google_ads.py]"]
end

subgraph group_operations["Account operations"]
  node_gateway["Google Ads gateway<br/>[google_ads.py]"]
  node_budget_inspection["Budget inspection<br/>[google_ads.py]"]
  node_budget_mutation["Budget updates<br/>[google_ads.py]"]
  node_campaign_status["Campaign status<br/>[google_ads.py]"]
  node_conversion_controls["Conversion goals<br/>[google_ads.py]"]
  node_negative_keywords["Negative keywords<br/>[google_ads.py]"]
  node_recommendations["Recommendations<br/>[google_ads.py]"]
end

subgraph group_safeguards["Safety and audit"]
  node_settings["Account settings<br/>[config.py]"]
  node_policy["Write policy<br/>[policy.py]"]
  node_audit_logger["Audit logger<br/>[audit.py]"]
  node_audit_files[("JSONL audit files")]
end

node_mcp_client(("MCP client"))
node_google_ads_api["Google Ads API"]

node_mcp_client -->|"invokes tools"| node_mcp_server
node_mcp_server -->|"loads settings"| node_settings
node_mcp_server -->|"dispatches requests"| node_gateway
node_mcp_server -->|"records writes"| node_audit_logger
node_helper_cli -->|"loads settings"| node_settings
node_helper_cli -->|"runs queries"| node_gateway
node_gateway -->|"validates limits"| node_policy
node_gateway -->|"calls API"| node_google_ads_api
node_mcp_server -->|"requests customer list"| node_customer_access
node_mcp_server -->|"runs queries"| node_gaql_search
node_mcp_server -->|"resolves places"| node_geo_targets
node_mcp_server -->|"requests ideas"| node_keyword_ideas
node_mcp_server -->|"requests forecast"| node_keyword_forecast
node_mcp_server -.->|"inspects budgets"| node_budget_inspection
node_mcp_server -->|"sets budgets"| node_budget_mutation
node_mcp_server -->|"changes status"| node_campaign_status
node_mcp_server -->|"updates goals"| node_conversion_controls
node_mcp_server -->|"adds negatives"| node_negative_keywords
node_mcp_server -.->|"applies recommendations"| node_recommendations
node_audit_logger -->|"appends records"| node_audit_files

click node_mcp_server "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/mcp_server.py"
click node_helper_cli "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/cli.py"
click node_settings "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/config.py"
click node_gateway "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_customer_access "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_gaql_search "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_geo_targets "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_keyword_ideas "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_keyword_forecast "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_budget_inspection "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_budget_mutation "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_campaign_status "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_conversion_controls "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_negative_keywords "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_recommendations "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py"
click node_policy "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/policy.py"
click node_audit_logger "https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/audit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_helper_cli,node_mcp_client toneBlue
class node_customer_access,node_gaql_search,node_geo_targets,node_keyword_ideas,node_keyword_forecast toneAmber
class node_gateway,node_budget_inspection,node_budget_mutation,node_campaign_status,node_conversion_controls,node_negative_keywords,node_recommendations,node_google_ads_api toneMint
class node_settings,node_policy,node_audit_logger,node_audit_files toneRose
```

## Components

### Operator interfaces

- [MCP tools](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/mcp_server.py): `src/google_ads_mcp/mcp_server.py`
- [Helper CLI](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/cli.py): `src/google_ads_mcp/cli.py`

### Reporting and planning

- [Customer access](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [GAQL reporting](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Geo targeting](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Keyword ideas](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Search forecast](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`

### Account operations

- [Google Ads gateway](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Budget inspection](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Budget updates](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Campaign status](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Conversion goals](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Negative keywords](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`
- [Recommendations](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/google_ads.py): `src/google_ads_mcp/google_ads.py`

### Safety and audit

- [Account settings](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/config.py): `src/google_ads_mcp/config.py`
- [Write policy](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/policy.py): `src/google_ads_mcp/policy.py`
- [Audit logger](https://github.com/connorcallison/google-ads-mcp/blob/main/src/google_ads_mcp/audit.py): `src/google_ads_mcp/audit.py`
- **JSONL audit files**

### Other components

- **MCP client**
- **Google Ads API**

## Connections

- MCP client → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Account settings: loads settings (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Google Ads gateway: dispatches requests (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Audit logger: records writes (evidence: `src/google_ads_mcp/mcp_server.py`)
- Helper CLI → Account settings: loads settings (evidence: `src/google_ads_mcp/cli.py`)
- Helper CLI → Google Ads gateway: runs queries (evidence: `src/google_ads_mcp/cli.py`)
- Google Ads gateway → Write policy: validates limits (evidence: `src/google_ads_mcp/google_ads.py`)
- Google Ads gateway → Google Ads API: calls API (evidence: `src/google_ads_mcp/google_ads.py`)
- MCP tools → Customer access: requests customer list (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → GAQL reporting: runs queries (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Geo targeting: resolves places (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Keyword ideas: requests ideas (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Search forecast: requests forecast (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Budget inspection: inspects budgets (evidence: `README.md`)
- MCP tools → Budget updates: sets budgets (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Campaign status: changes status (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Conversion goals: updates goals (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Negative keywords: adds negatives (evidence: `src/google_ads_mcp/mcp_server.py`)
- MCP tools → Recommendations: applies recommendations (evidence: `README.md`)
- Audit logger → JSONL audit files: appends records (evidence: `src/google_ads_mcp/audit.py`)
