# fgribreau/mcp-google-ads architecture

> Architecture diagram of the GitHub repository fgribreau/mcp-google-ads, 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/fgribreau/mcp-google-ads
- Repository: https://github.com/fgribreau/mcp-google-ads

## Overview

mcp-google-ads is an MCP server that lets Claude inspect and manage Google Ads accounts. The principal workflow is a tool request, a Google Ads read or mutation draft, a reviewable preview, then explicit confirmation before a write is applied and audited. Its tool surface also covers reporting, keyword planning, audiences, bidding, geo targeting, policy, conversions, and other account operations. The source excerpts show the MCP dispatch and parts of the safety and client layers; README statements support the broader tool coverage. Some subsystem links are therefore documented rather than verified in sampled implementation.

Main entry points: [`src/client.rs`](https://github.com/fgribreau/mcp-google-ads/blob/main/src/client.rs) (Google Ads client), [`src/lib.rs`](https://github.com/fgribreau/mcp-google-ads/blob/main/src/lib.rs) (Tool dispatch), [`src/tools/keywords_write.rs`](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/keywords_write.rs) (Keyword tools), [`src/tools/confirm.rs`](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/confirm.rs) (Apply confirmation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server_runtime["Tool dispatch<br/>[lib.rs]"]
end

subgraph group_ads_tools["Ads operations"]
  node_campaign_reads["Campaign reporting<br/>[campaigns.rs]"]
  node_keyword_tools["Keyword tools<br/>[keywords_write.rs]"]
  node_shared_sets["Negative keyword lists"]
  node_campaign_writes["Campaign changes<br/>[campaigns_write.rs]"]
  node_demographics["Demographic tools<br/>[demographics.rs]"]
  node_other_ads_tools["Other Ads capabilities"]
end

subgraph group_safety["Safety workflow"]
  node_preview[("Pending change plans<br/>[preview.rs]")]
  node_guards["Mutation guardrails<br/>[guards.rs]"]
  node_policy_exemption["Policy exemptions"]
  node_confirmation["Apply confirmation<br/>[confirm.rs]"]
  node_audit["Mutation audit log<br/>[audit.rs]"]
end

subgraph group_foundation["API foundation"]
  node_config["Environment config<br/>[config.rs]"]
  node_auth["OAuth authentication<br/>[auth.rs]"]
  node_ads_client["Google Ads client<br/>[client.rs]"]
  node_gaql["GAQL formatting<br/>[gaql.rs]"]
  node_shared_models["Shared domain models<br/>[demographic.rs]"]
  node_errors["API error handling<br/>[error.rs]"]
end

node_claude(("Claude / MCP host"))
node_google_ads["Google Ads API"]

node_claude -->|"sends tool requests"| node_server_runtime
node_server_runtime -->|"dispatches reads"| node_campaign_reads
node_server_runtime -->|"dispatches writes"| node_keyword_tools
node_server_runtime -->|"dispatches reads"| node_demographics
node_server_runtime -->|"exposes tools"| node_other_ads_tools
node_server_runtime -.->|"uses configuration"| node_config
node_campaign_reads -->|"queries account"| node_ads_client
node_campaign_reads -->|"uses query helpers"| node_gaql
node_keyword_tools -->|"mutates account"| node_ads_client
node_keyword_tools -->|"creates preview"| node_preview
node_shared_sets -->|"mutates account"| node_ads_client
node_shared_sets -->|"creates preview"| node_preview
node_campaign_writes -->|"creates preview"| node_preview
node_demographics -->|"queries account"| node_ads_client
node_demographics -->|"uses models"| node_shared_models
node_preview -->|"requests confirmation"| node_confirmation
node_confirmation -->|"applies mutations"| node_ads_client
node_confirmation -->|"records mutation"| node_audit
node_confirmation -->|"handles policy errors"| node_policy_exemption
node_campaign_writes -->|"checks write limits"| node_guards
node_ads_client -->|"obtains credentials"| node_auth
node_auth -->|"reads settings"| node_config
node_ads_client -->|"sends API requests"| node_google_ads
node_ads_client -->|"parses API failures"| node_errors
node_keyword_tools -->|"supports exemptions"| node_policy_exemption
node_other_ads_tools -.->|"accesses API"| node_ads_client

click node_server_runtime "https://github.com/fgribreau/mcp-google-ads/blob/main/src/lib.rs"
click node_config "https://github.com/fgribreau/mcp-google-ads/blob/main/src/config.rs"
click node_auth "https://github.com/fgribreau/mcp-google-ads/blob/main/src/auth.rs"
click node_ads_client "https://github.com/fgribreau/mcp-google-ads/blob/main/src/client.rs"
click node_gaql "https://github.com/fgribreau/mcp-google-ads/blob/main/src/gaql.rs"
click node_shared_models "https://github.com/fgribreau/mcp-google-ads/blob/main/src/models/demographic.rs"
click node_campaign_reads "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/campaigns.rs"
click node_keyword_tools "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/keywords_write.rs"
click node_shared_sets "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/shared_sets_write.rs"
click node_campaign_writes "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/campaigns_write.rs"
click node_demographics "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/demographics.rs"
click node_other_ads_tools "https://github.com/fgribreau/mcp-google-ads/tree/main/src/tools"
click node_preview "https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/preview.rs"
click node_guards "https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/guards.rs"
click node_policy_exemption "https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/policy_exemption.rs"
click node_confirmation "https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/confirm.rs"
click node_audit "https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/audit.rs"
click node_errors "https://github.com/fgribreau/mcp-google-ads/blob/main/src/error.rs"

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_server_runtime toneBlue
class node_campaign_reads,node_keyword_tools,node_shared_sets,node_campaign_writes,node_demographics,node_other_ads_tools toneAmber
class node_preview,node_guards,node_policy_exemption,node_confirmation,node_audit,node_google_ads toneMint
class node_config,node_auth,node_ads_client,node_gaql,node_shared_models,node_errors toneRose
class node_claude toneIndigo
```

## Components

### MCP server

- [Tool dispatch](https://github.com/fgribreau/mcp-google-ads/blob/main/src/lib.rs): `src/lib.rs`

### Ads operations

- [Campaign reporting](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/campaigns.rs): `src/tools/campaigns.rs`
- [Keyword tools](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/keywords_write.rs): `src/tools/keywords_write.rs`
- [Negative keyword lists](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/shared_sets_write.rs): `src/tools/shared_sets_write.rs`
- [Campaign changes](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/campaigns_write.rs): `src/tools/campaigns_write.rs`
- [Demographic tools](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/demographics.rs): `src/tools/demographics.rs`
- [Other Ads capabilities](https://github.com/fgribreau/mcp-google-ads/tree/main/src/tools): `src/tools`

### Safety workflow

- [Pending change plans](https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/preview.rs): `src/safety/preview.rs`
- [Mutation guardrails](https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/guards.rs): `src/safety/guards.rs`
- [Policy exemptions](https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/policy_exemption.rs): `src/safety/policy_exemption.rs`
- [Apply confirmation](https://github.com/fgribreau/mcp-google-ads/blob/main/src/tools/confirm.rs): `src/tools/confirm.rs`
- [Mutation audit log](https://github.com/fgribreau/mcp-google-ads/blob/main/src/safety/audit.rs): `src/safety/audit.rs`

### API foundation

- [Environment config](https://github.com/fgribreau/mcp-google-ads/blob/main/src/config.rs): `src/config.rs`
- [OAuth authentication](https://github.com/fgribreau/mcp-google-ads/blob/main/src/auth.rs): `src/auth.rs`
- [Google Ads client](https://github.com/fgribreau/mcp-google-ads/blob/main/src/client.rs): `src/client.rs`
- [GAQL formatting](https://github.com/fgribreau/mcp-google-ads/blob/main/src/gaql.rs): `src/gaql.rs`
- [Shared domain models](https://github.com/fgribreau/mcp-google-ads/blob/main/src/models/demographic.rs): `src/models/demographic.rs`
- [API error handling](https://github.com/fgribreau/mcp-google-ads/blob/main/src/error.rs): `src/error.rs`

### Other components

- **Claude / MCP host**
- **Google Ads API**

## Connections

- Claude / MCP host → Tool dispatch: sends tool requests (evidence: `README.md`)
- Tool dispatch → Campaign reporting: dispatches reads (evidence: `src/lib.rs`)
- Tool dispatch → Keyword tools: dispatches writes (evidence: `src/lib.rs`)
- Tool dispatch → Demographic tools: dispatches reads (evidence: `src/lib.rs`)
- Tool dispatch → Other Ads capabilities: exposes tools (evidence: `README.md`)
- Tool dispatch → Environment config: uses configuration (evidence: `src/lib.rs`)
- Campaign reporting → Google Ads client: queries account (evidence: `src/tools/campaigns.rs`)
- Campaign reporting → GAQL formatting: uses query helpers (evidence: `src/tools/campaigns.rs`)
- Keyword tools → Google Ads client: mutates account (evidence: `src/tools/keywords_write.rs`)
- Keyword tools → Pending change plans: creates preview (evidence: `src/tools/keywords_write.rs`)
- Negative keyword lists → Google Ads client: mutates account (evidence: `src/tools/shared_sets_write.rs`)
- Negative keyword lists → Pending change plans: creates preview (evidence: `src/tools/shared_sets_write.rs`)
- Campaign changes → Pending change plans: creates preview (evidence: `src/tools/campaigns_write.rs`)
- Demographic tools → Google Ads client: queries account (evidence: `src/tools/demographics.rs`)
- Demographic tools → Shared domain models: uses models (evidence: `src/models/demographic.rs`)
- Pending change plans → Apply confirmation: requests confirmation (evidence: `src/safety/preview.rs`)
- Apply confirmation → Google Ads client: applies mutations (evidence: `src/tools/confirm.rs`)
- Apply confirmation → Mutation audit log: records mutation (evidence: `src/tools/confirm.rs`)
- Apply confirmation → Policy exemptions: handles policy errors (evidence: `src/tools/confirm.rs`)
- Campaign changes → Mutation guardrails: checks write limits (evidence: `src/tools/campaigns_write.rs`)
- Google Ads client → OAuth authentication: obtains credentials (evidence: `src/client.rs`)
- OAuth authentication → Environment config: reads settings (evidence: `src/auth.rs`)
- Google Ads client → Google Ads API: sends API requests (evidence: `src/client.rs`)
- Google Ads client → API error handling: parses API failures (evidence: `src/client.rs`)
- Keyword tools → Policy exemptions: supports exemptions (evidence: `src/tools/keywords_write.rs`)
- Other Ads capabilities → Google Ads client: accesses API (evidence: `src/tools/campaigns_write.rs`)
