# cohnen/mcp-google-ads architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Python-based microservice (“Google Ads MCP Server”) that exposes a set of “tools” (list_accounts, execute_gaql_query, etc.) to AI-driven clients (Claude AI assistant and Cursor AI code editor).
- Its sole purpose is to connect to the Google Ads API, fetch advertising data, and present it in natural-language or structured form to the AI clients.

##### File Structure Analysis
- Top-level code artifacts:
- google_ads_server.py – the entrypoint for the MCP server
- format_customer_id_test.py, test_google_ads_mcp.py, test_token_refresh.py – unit tests for core functionality and authentication
- requirements.txt / pyproject.toml – Python dependencies (e.g., google-ads, mcp)
- Configuration & docs:
- .env.example – environment variable template
- .cursor/ – Cursor AI editor integration rules
- docs/ – markdown documentation for each tool
- No frontend code; all logic lives in the MCP server and supporting test/config files.

##### README Insights
- Describes two auth methods (OAuth2, Service Account) and environment/configuration flows.

##### Detailed Steps for Drafting
1. Sketch Users at the left, AI Clients next, MCP Server in the center, Google Ads API at the right.
a. FastMCP Core
b. Tools Layer (with bullet list of tool names)
c. Auth Module ← Credentials (OAuth2 JSON / Service account JSON)
– User → Claude / Cursor (“chat & tool requests”)
– Claude / Cursor → MCP Server (“invoke <tool>”)
– MCP Server → Google Ads API (“REST/gRPC call with credentials”)
– Google Ads API → MCP Server (“AdData JSON”)
– MCP Server → Claude / Cursor (“formatted results”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    subgraph "AI Clients"
        Claude["Claude AI Assistant"]:::ai
        Cursor["Cursor AI Code Editor"]:::ai
    end

    subgraph "Google Ads MCP Server"
        direction TB
        GEntry["google_ads_server.py\n(Entrypoint & Tool Registrations)"]:::server
        FastMCP["FastMCP Core"]:::server
        Tools["Tools Plugin Layer\n(list_accounts, execute_gaql_query,\nget_campaign_performance, get_ad_performance, run_gaql)"]:::server
        Auth["Authentication Module\n(OAuth2 & Service Account)"]:::server
        Config["Configuration Loader\n(.env, JSON configs)"]:::config
    end

    GoogleAPI["Google Ads API"]:::external

    subgraph "Project Artifacts"
        direction TB
        D1["docs/fastmcp.md"]:::docs
        D2["docs/gaql-google-ads-query-language.md"]:::docs
        D3[".cursor/rules/gaql-google-ads-query-language.mdc"]:::docs
        D4[".cursor/rules/fastmcp.mdc"]:::docs
        MD["README.md"]:::docs
        Lic["LICENSE"]:::docs
        ReqTxt["requirements.txt"]:::docs
        PyProj["pyproject.toml"]:::docs
        Env[".env.example"]:::config
        T1["format_customer_id_test.py"]:::tests
        T2["test_google_ads_mcp.py"]:::tests
        T3["test_token_refresh.py"]:::tests
        Pulls["pulls/"]:::docs
    end

    User -->|"chat & tool requests"| Claude
    User -->|"chat & tool requests"| Cursor

    Claude -->|"invoke tool"| GEntry
    Cursor -->|"invoke tool"| GEntry

    GEntry --> FastMCP
    GEntry --> Tools
    GEntry --> Auth
    Config --> GEntry

    FastMCP -->|"registers tools"| Tools
    Tools -->|"requires creds"| Auth
    Auth -->|"REST/gRPC call with credentials"| GoogleAPI
    GoogleAPI -->|"AdData JSON"| Tools
    Tools -->|"formatted results"| Claude
    Tools -->|"formatted results"| Cursor

    Config --> FastMCP
    Config --> Auth
    Config --> Tools

    GEntry --> D1
    Tools --> D2
    Tools --> D3
    FastMCP --> D4

    Auth --> T3
    GEntry --> T2
    GEntry --> T1

    Config --> Env
    ReqTxt --> PyProj

    MD --> Lic
    MD --> Pulls

    classDef ai fill:#8FBC8F,stroke:#333,stroke-width:1px;
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef docs fill:#F0E68C,stroke:#333,stroke-width:1px;
    classDef tests fill:#FFC0CB,stroke:#333,stroke-width:1px;
    classDef user fill:#E0E0E0,stroke:#333,stroke-width:1px;

    click GEntry "https://github.com/cohnen/mcp-google-ads/blob/main/google_ads_server.py"
    click FastMCP "https://github.com/cohnen/mcp-google-ads/blob/main/docs/fastmcp.md"
    click Tools "https://github.com/cohnen/mcp-google-ads/blob/main/google_ads_server.py"
    click D1 "https://github.com/cohnen/mcp-google-ads/blob/main/docs/fastmcp.md"
    click D2 "https://github.com/cohnen/mcp-google-ads/blob/main/docs/gaql-google-ads-query-language.md"
    click D3 "https://github.com/cohnen/mcp-google-ads/blob/main/.cursor/rules/gaql-google-ads-query-language.mdc"
    click D4 "https://github.com/cohnen/mcp-google-ads/blob/main/.cursor/rules/fastmcp.mdc"
    click Auth "https://github.com/cohnen/mcp-google-ads/blob/main/test_token_refresh.py"
    click T1 "https://github.com/cohnen/mcp-google-ads/blob/main/format_customer_id_test.py"
    click T2 "https://github.com/cohnen/mcp-google-ads/blob/main/test_google_ads_mcp.py"
    click T3 "https://github.com/cohnen/mcp-google-ads/blob/main/test_token_refresh.py"
    click Env "https://github.com/cohnen/mcp-google-ads/blob/main/.env.example"
    click ReqTxt "https://github.com/cohnen/mcp-google-ads/blob/main/requirements.txt"
    click PyProj "https://github.com/cohnen/mcp-google-ads/blob/main/pyproject.toml"
    click MD "https://github.com/cohnen/mcp-google-ads/blob/main/README.md"
    click Lic "https://github.com/cohnen/mcp-google-ads/tree/main/LICENSE"
    click Pulls "https://github.com/cohnen/mcp-google-ads/tree/main/pulls/"
```
