# getmcpads-com/google-ads-mcp-server architecture

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

## Overview

This repository is a standalone Google Ads MCP server. The main workflow is an MCP client requesting account or performance data, the registered Google Ads tools planning or dispatching reads to Google, and returning results through MCP. It also supports keyword planning, catalog/resource discovery, and opt-in campaign writes with previews. The graph follows documented capabilities and visible imports/calls; unsampled subsystem links are omitted where their runtime wiring cannot be verified.

Main entry points: [`src/platforms/google-ads/client.ts`](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/client.ts) (Google Ads client), [`src/platforms/google-ads/index.ts`](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/index.ts) (Google Ads registration), [`src/platforms/google-ads/query-planner.ts`](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/query-planner.ts) (GAQL query planner), [`src/server.ts`](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server entry"]
  node_server["MCP server<br/>[server.ts]"]
  node_config["Credentials config<br/>[config.ts]"]
  node_registrar["Google Ads registration<br/>[index.ts]"]
end

subgraph group_read["Read planning"]
  node_read_tools["Read tools<br/>[tools.ts]"]
  node_query_planner["GAQL query planner<br/>[query-planner.ts]"]
  node_metric_catalog["Metric catalog<br/>[metric-catalog.ts]"]
  node_dimension_catalog["Dimension catalog"]
  node_compatibility["Compatibility rules"]
  node_filter_catalog["Filter catalog<br/>[filter-catalog.ts]"]
  node_ads_client["Google Ads client<br/>[client.ts]"]
end

subgraph group_account["Account and research"]
  node_keyword_planner["Keyword Planner<br/>[keyword-planner.ts]"]
  node_discovery["Account discovery<br/>[discovery-tools.ts]"]
  node_read_rpc["Read-only RPC<br/>[read-rpc.ts]"]
  node_resources["MCP resources<br/>[resources.ts]"]
end

subgraph group_changes["Campaign changes"]
  node_writes["Campaign writes<br/>[writes.ts]"]
  node_extended_writes["Extended writes<br/>[extended-writes.ts]"]
end

subgraph group_support["Shared services"]
  node_quality["Tool quality<br/>[tool-quality.ts]"]
  node_parameters["Parameter descriptions"]
  node_errors["Error formatting<br/>[errors.ts]"]
  node_rate_limiter["Rate limiting<br/>[rate-limiter.ts]"]
  node_money["Money conversion<br/>[money.ts]"]
end

node_mcp_client(("MCP client"))
node_google_ads(("Google Ads API"))

node_mcp_client -->|"sends requests"| node_server
node_server -->|"uses config"| node_config
node_server -->|"registers tools"| node_registrar
node_server -->|"installs metadata"| node_quality
node_registrar -->|"registers reads"| node_read_tools
node_read_tools -->|"plans queries"| node_query_planner
node_query_planner -->|"resolves metrics"| node_metric_catalog
node_query_planner -.->|"resolves dimensions"| node_dimension_catalog
node_query_planner -->|"checks selection"| node_compatibility
node_query_planner -->|"builds filters"| node_filter_catalog
node_read_tools -->|"executes reads"| node_ads_client
node_ads_client -->|"plans requests"| node_query_planner
node_ads_client -->|"calls API"| node_google_ads
node_registrar -.->|"registers discovery"| node_discovery
node_discovery -->|"uses client"| node_ads_client
node_registrar -->|"registers resources"| node_resources
node_registrar -->|"registers writes"| node_writes
node_writes -->|"delegates writes"| node_extended_writes
node_registrar -->|"registers extensions"| node_extended_writes
node_writes -->|"converts amounts"| node_money
node_quality -->|"adds descriptions"| node_parameters
node_read_tools -->|"formats failures"| node_errors
node_ads_client -->|"limits requests"| node_rate_limiter
node_keyword_planner -->|"uses client"| node_ads_client
node_read_rpc -->|"uses client"| node_ads_client
node_google_ads -.->|"returns results"| node_mcp_client

click node_server "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/server.ts"
click node_config "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/config.ts"
click node_registrar "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/index.ts"
click node_read_tools "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/tools.ts"
click node_query_planner "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/query-planner.ts"
click node_metric_catalog "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/metric-catalog.ts"
click node_dimension_catalog "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/dimension-catalog.ts"
click node_compatibility "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/compatibility-rules.ts"
click node_filter_catalog "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/filter-catalog.ts"
click node_ads_client "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/client.ts"
click node_keyword_planner "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/keyword-planner.ts"
click node_discovery "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/discovery-tools.ts"
click node_read_rpc "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/read-rpc.ts"
click node_resources "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/resources.ts"
click node_writes "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/writes.ts"
click node_extended_writes "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/extended-writes.ts"
click node_quality "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/tool-quality.ts"
click node_parameters "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/parameter-descriptions.ts"
click node_errors "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/errors.ts"
click node_rate_limiter "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/rate-limiter.ts"
click node_money "https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/money.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_server,node_config,node_registrar,node_mcp_client toneBlue
class node_read_tools,node_query_planner,node_metric_catalog,node_dimension_catalog,node_compatibility,node_filter_catalog,node_ads_client toneAmber
class node_keyword_planner,node_discovery,node_read_rpc,node_resources,node_google_ads toneMint
class node_writes,node_extended_writes toneRose
class node_quality,node_parameters,node_errors,node_rate_limiter,node_money toneIndigo
```

## Components

### Server entry

- [MCP server](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/server.ts): `src/server.ts`
- [Credentials config](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/config.ts): `src/config.ts`
- [Google Ads registration](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/index.ts): `src/platforms/google-ads/index.ts`

### Read planning

- [Read tools](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/tools.ts): `src/platforms/google-ads/tools.ts`
- [GAQL query planner](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/query-planner.ts): `src/platforms/google-ads/query-planner.ts`
- [Metric catalog](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/metric-catalog.ts): `src/platforms/google-ads/metric-catalog.ts`
- [Dimension catalog](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/dimension-catalog.ts): `src/platforms/google-ads/dimension-catalog.ts`
- [Compatibility rules](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/compatibility-rules.ts): `src/platforms/google-ads/compatibility-rules.ts`
- [Filter catalog](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/filter-catalog.ts): `src/platforms/google-ads/filter-catalog.ts`
- [Google Ads client](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/client.ts): `src/platforms/google-ads/client.ts`

### Account and research

- [Keyword Planner](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/keyword-planner.ts): `src/platforms/google-ads/keyword-planner.ts`
- [Account discovery](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/discovery-tools.ts): `src/platforms/google-ads/discovery-tools.ts`
- [Read-only RPC](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/read-rpc.ts): `src/platforms/google-ads/read-rpc.ts`
- [MCP resources](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/resources.ts): `src/platforms/google-ads/resources.ts`

### Campaign changes

- [Campaign writes](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/writes.ts): `src/platforms/google-ads/writes.ts`
- [Extended writes](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/platforms/google-ads/extended-writes.ts): `src/platforms/google-ads/extended-writes.ts`

### Shared services

- [Tool quality](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/tool-quality.ts): `src/tool-quality.ts`
- [Parameter descriptions](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/parameter-descriptions.ts): `src/parameter-descriptions.ts`
- [Error formatting](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/errors.ts): `src/core/errors.ts`
- [Rate limiting](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/rate-limiter.ts): `src/core/rate-limiter.ts`
- [Money conversion](https://github.com/getmcpads-com/google-ads-mcp-server/blob/main/src/core/money.ts): `src/core/money.ts`

### Other components

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

## Connections

- MCP client → MCP server: sends requests (evidence: `README.md`)
- MCP server → Credentials config: uses config (evidence: `src/server.ts`)
- MCP server → Google Ads registration: registers tools (evidence: `src/server.ts`)
- MCP server → Tool quality: installs metadata (evidence: `src/server.ts`)
- Google Ads registration → Read tools: registers reads (evidence: `src/platforms/google-ads/index.ts`)
- Read tools → GAQL query planner: plans queries (evidence: `src/platforms/google-ads/tools.ts`)
- GAQL query planner → Metric catalog: resolves metrics (evidence: `src/platforms/google-ads/query-planner.ts`)
- GAQL query planner → Dimension catalog: resolves dimensions (evidence: `src/platforms/google-ads/query-planner.ts`)
- GAQL query planner → Compatibility rules: checks selection (evidence: `src/platforms/google-ads/query-planner.ts`)
- GAQL query planner → Filter catalog: builds filters (evidence: `src/platforms/google-ads/query-planner.ts`)
- Read tools → Google Ads client: executes reads (evidence: `src/platforms/google-ads/tools.ts`)
- Google Ads client → GAQL query planner: plans requests (evidence: `src/platforms/google-ads/client.ts`)
- Google Ads client → Google Ads API: calls API (evidence: `README.md`)
- Google Ads registration → Account discovery: registers discovery (evidence: `src/platforms/google-ads/index.ts`)
- Account discovery → Google Ads client: uses client (evidence: `src/platforms/google-ads/discovery-tools.ts`)
- Google Ads registration → MCP resources: registers resources (evidence: `src/platforms/google-ads/index.ts`)
- Google Ads registration → Campaign writes: registers writes (evidence: `src/platforms/google-ads/index.ts`)
- Campaign writes → Extended writes: delegates writes (evidence: `src/platforms/google-ads/writes.ts`)
- Google Ads registration → Extended writes: registers extensions (evidence: `src/platforms/google-ads/index.ts`)
- Campaign writes → Money conversion: converts amounts (evidence: `src/platforms/google-ads/writes.ts`)
- Tool quality → Parameter descriptions: adds descriptions (evidence: `src/tool-quality.ts`)
- Read tools → Error formatting: formats failures (evidence: `src/platforms/google-ads/tools.ts`)
- Google Ads client → Rate limiting: limits requests (evidence: `src/platforms/google-ads/client.ts`)
- Keyword Planner → Google Ads client: uses client (evidence: `src/platforms/google-ads/keyword-planner.ts`)
- Read-only RPC → Google Ads client: uses client (evidence: `src/platforms/google-ads/read-rpc.ts`)
- Google Ads API → MCP client: returns results (evidence: `README.md`)
