# davidmosiah/google-ads-mcp-unofficial architecture

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

## Overview

This repository is a local-first MCP server that lets AI agents inspect Google Ads accounts, analyze performance, and make explicitly authorized, gated changes. The principal workflow is: an agent invokes an MCP tool, the tool applies configuration and privacy rules, the Google Ads client fetches or mutates account data, and the tool returns a formatted response. Setup and OAuth establish credentials; diagnostics, reporting, profile, inventory, and audit tools provide supporting capabilities. Relationships are based on the README and SOURCE INDEX references; unsampled tool internals are represented at the module level.

Main entry points: [`src/tools/google-ads-tools.ts`](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/tools/google-ads-tools.ts) (MCP Tools), [`src/services/google-ads-client.ts`](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/google-ads-client.ts) (Google Ads Client), [`src/cli/commands.ts`](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/commands.ts) (CLI Commands), [`src/cli/auth.ts`](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/auth.ts) (OAuth Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["MCP And CLI"]
  node_entry["Server Entry<br/>[index.ts]"]
  node_cli["CLI Commands<br/>[commands.ts]"]
  node_toolcall["CLI Tool Calls<br/>[tool-calls.ts]"]
  node_manifest["Agent Manifest<br/>[agent-manifest.ts]"]
end

subgraph group_auth["Setup And Credentials"]
  node_setup["Setup Wizard<br/>[setup.ts]"]
  node_authflow["OAuth Flow<br/>[auth.ts]"]
  node_config["Config Resolution<br/>[config.ts]"]
  node_localconfig["Local Config<br/>[local-config.ts]"]
  node_tokens["Token Store<br/>[token-store.ts]"]
end

subgraph group_ads["Google Ads Operations"]
  node_tools["MCP Tools"]
  node_googleclient["Google Ads Client"]
  node_cache[("SQLite Cache<br/>[cache.ts]")]
  node_retry["HTTP Retry<br/>[http-retry.ts]"]
  node_format["Response Formatting<br/>[format.ts]"]
  node_schema["Tool Schemas<br/>[common.ts]"]
end

subgraph group_safety["Privacy And Diagnostics"]
  node_privacy["Privacy Modes<br/>[privacy.ts]"]
  node_redaction["Redaction<br/>[redaction.ts]"]
  node_audit["Privacy Audit<br/>[audit.ts]"]
  node_profile["Shared Profile<br/>[profile-store.ts]"]
  node_status["Connection Status"]
  node_capabilities["Capabilities<br/>[capabilities.ts]"]
  node_inventory["Data Inventory<br/>[inventory.ts]"]
end

node_agent(("AI Agent"))
node_googleapi["Google Ads API"]
node_oauth["Google OAuth"]

node_agent -->|"invokes MCP"| node_entry
node_entry -->|"registers tools"| node_tools
node_entry -->|"dispatches commands"| node_cli
node_cli -->|"runs setup"| node_setup
node_cli -->|"runs auth"| node_authflow
node_cli -->|"runs tool call"| node_toolcall
node_toolcall -->|"calls tool"| node_tools
node_setup -->|"writes config"| node_localconfig
node_setup -->|"starts OAuth"| node_authflow
node_authflow -->|"loads config"| node_config
node_authflow -->|"exchanges code"| node_googleclient
node_googleclient -->|"requests tokens"| node_oauth
node_googleclient -->|"stores tokens"| node_tokens
node_tools -->|"queries account"| node_googleclient
node_googleclient -->|"sends API requests"| node_googleapi
node_googleclient -->|"reads or writes"| node_cache
node_googleclient -->|"retries requests"| node_retry
node_tools -->|"validates inputs"| node_schema
node_tools -->|"resolves settings"| node_config
node_config -->|"loads sources"| node_localconfig
node_tools -->|"formats responses"| node_format
node_tools -->|"resolves mode"| node_privacy
node_privacy -->|"redacts output"| node_redaction
node_tools -->|"redacts identifiers"| node_redaction
node_tools -->|"runs audit"| node_audit
node_tools -->|"reads or updates"| node_profile
node_tools -->|"checks connection"| node_status
node_tools -->|"reports capabilities"| node_capabilities
node_tools -->|"reports inventory"| node_inventory
node_tools -->|"provides manifest"| node_manifest
node_cli -->|"runs diagnostics"| node_status
node_cli -->|"selects client"| node_manifest

click node_entry "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/index.ts"
click node_cli "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/commands.ts"
click node_toolcall "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/tool-calls.ts"
click node_tools "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/tools/google-ads-tools.ts"
click node_setup "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/setup.ts"
click node_authflow "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/auth.ts"
click node_config "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/config.ts"
click node_localconfig "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/local-config.ts"
click node_tokens "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/token-store.ts"
click node_googleclient "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/google-ads-client.ts"
click node_cache "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/cache.ts"
click node_retry "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/http-retry.ts"
click node_format "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/format.ts"
click node_privacy "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/privacy.ts"
click node_redaction "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/redaction.ts"
click node_audit "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/audit.ts"
click node_profile "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/profile-store.ts"
click node_status "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/connection-status.ts"
click node_capabilities "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/capabilities.ts"
click node_inventory "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/inventory.ts"
click node_manifest "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/agent-manifest.ts"
click node_schema "https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/schemas/common.ts"

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_entry,node_cli,node_toolcall,node_manifest toneBlue
class node_setup,node_authflow,node_config,node_localconfig,node_tokens toneAmber
class node_tools,node_googleclient,node_cache,node_retry,node_format,node_schema,node_googleapi toneMint
class node_privacy,node_redaction,node_audit,node_profile,node_status,node_capabilities,node_inventory toneRose
class node_agent,node_oauth toneIndigo
```

## Components

### MCP And CLI

- [Server Entry](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/index.ts): `src/index.ts`
- [CLI Commands](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/commands.ts): `src/cli/commands.ts`
- [CLI Tool Calls](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/tool-calls.ts): `src/cli/tool-calls.ts`
- [Agent Manifest](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/agent-manifest.ts): `src/services/agent-manifest.ts`

### Setup And Credentials

- [Setup Wizard](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/setup.ts): `src/cli/setup.ts`
- [OAuth Flow](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/cli/auth.ts): `src/cli/auth.ts`
- [Config Resolution](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/config.ts): `src/services/config.ts`
- [Local Config](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/local-config.ts): `src/services/local-config.ts`
- [Token Store](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/token-store.ts): `src/services/token-store.ts`

### Google Ads Operations

- [MCP Tools](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/tools/google-ads-tools.ts): `src/tools/google-ads-tools.ts`
- [Google Ads Client](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/google-ads-client.ts): `src/services/google-ads-client.ts`
- [SQLite Cache](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/cache.ts): `src/services/cache.ts`
- [HTTP Retry](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/http-retry.ts): `src/services/http-retry.ts`
- [Response Formatting](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/format.ts): `src/services/format.ts`
- [Tool Schemas](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/schemas/common.ts): `src/schemas/common.ts`

### Privacy And Diagnostics

- [Privacy Modes](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/privacy.ts): `src/services/privacy.ts`
- [Redaction](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/redaction.ts): `src/services/redaction.ts`
- [Privacy Audit](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/audit.ts): `src/services/audit.ts`
- [Shared Profile](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/profile-store.ts): `src/services/profile-store.ts`
- [Connection Status](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/connection-status.ts): `src/services/connection-status.ts`
- [Capabilities](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/capabilities.ts): `src/services/capabilities.ts`
- [Data Inventory](https://github.com/davidmosiah/google-ads-mcp-unofficial/blob/main/src/services/inventory.ts): `src/services/inventory.ts`

### Other components

- **AI Agent**
- **Google Ads API**
- **Google OAuth**

## Connections

- AI Agent → Server Entry: invokes MCP (evidence: `README.md`)
- Server Entry → MCP Tools: registers tools (evidence: `src/index.ts`)
- Server Entry → CLI Commands: dispatches commands (evidence: `src/index.ts`)
- CLI Commands → Setup Wizard: runs setup (evidence: `src/cli/commands.ts`)
- CLI Commands → OAuth Flow: runs auth (evidence: `src/cli/commands.ts`)
- CLI Commands → CLI Tool Calls: runs tool call (evidence: `src/cli/commands.ts`)
- CLI Tool Calls → MCP Tools: calls tool (evidence: `src/cli/tool-calls.ts`)
- Setup Wizard → Local Config: writes config (evidence: `src/cli/setup.ts`)
- Setup Wizard → OAuth Flow: starts OAuth (evidence: `src/cli/setup.ts`)
- OAuth Flow → Config Resolution: loads config (evidence: `src/cli/auth.ts`)
- OAuth Flow → Google Ads Client: exchanges code (evidence: `src/cli/auth.ts`)
- Google Ads Client → Google OAuth: requests tokens (evidence: `src/services/google-ads-client.ts`)
- Google Ads Client → Token Store: stores tokens (evidence: `src/services/google-ads-client.ts`)
- MCP Tools → Google Ads Client: queries account (evidence: `src/tools/google-ads-tools.ts`)
- Google Ads Client → Google Ads API: sends API requests (evidence: `README.md`)
- Google Ads Client → SQLite Cache: reads or writes (evidence: `src/services/google-ads-client.ts`)
- Google Ads Client → HTTP Retry: retries requests (evidence: `src/services/google-ads-client.ts`)
- MCP Tools → Tool Schemas: validates inputs (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Config Resolution: resolves settings (evidence: `src/tools/google-ads-tools.ts`)
- Config Resolution → Local Config: loads sources (evidence: `src/services/config.ts`)
- MCP Tools → Response Formatting: formats responses (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Privacy Modes: resolves mode (evidence: `src/tools/google-ads-tools.ts`)
- Privacy Modes → Redaction: redacts output (evidence: `src/services/privacy.ts`)
- MCP Tools → Redaction: redacts identifiers (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Privacy Audit: runs audit (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Shared Profile: reads or updates (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Connection Status: checks connection (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Capabilities: reports capabilities (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Data Inventory: reports inventory (evidence: `src/tools/google-ads-tools.ts`)
- MCP Tools → Agent Manifest: provides manifest (evidence: `src/tools/google-ads-tools.ts`)
- CLI Commands → Connection Status: runs diagnostics (evidence: `src/cli/commands.ts`)
- CLI Commands → Agent Manifest: selects client (evidence: `src/cli/commands.ts`)
