# proxy-intell/google-ads-library-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/proxy-intell/google-ads-library-mcp
- Repository: https://github.com/proxy-intell/google-ads-library-mcp

## Overview

This is a self-hostable MCP server for searching Google Ads Transparency Center ads and analyzing their images and videos. The principal workflow is an MCP client request, handled by the Python server, which retrieves ads or ad details through ScrapeCreators and returns structured results. Image and video analysis add media caching; video analysis can also use Gemini. Cache statistics, search, and cleanup are separate user-facing capabilities. The Node launcher is a thin runtime entry point. Relationships reflect the excerpts and README; unsampled tool wiring is not inferred.

Main entry points: [`mcp_server.py`](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py) (MCP Server), [`src/services/media_cache_service.py`](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/media_cache_service.py) (Media Cache Service), [`index.js`](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/index.js) (Node Launcher), [`src/services/scrapecreators_service.py`](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/scrapecreators_service.py) (Ads API Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_launcher["Node Launcher<br/>[index.js]"]
  node_server["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_ads["Ad Retrieval"]
  node_ads_tools["Ad Tools<br/>[mcp_server.py]"]
  node_scrape["Ads API Service"]
  node_ads_api["ScrapeCreators API"]
end

subgraph group_analysis["Media Analysis"]
  node_image_analysis["Image Analysis<br/>[mcp_server.py]"]
  node_video_analysis["Video Analysis<br/>[mcp_server.py]"]
  node_gemini["Gemini Video AI"]
end

subgraph group_cache["Media Cache"]
  node_cache_tools["Cache Tools<br/>[mcp_server.py]"]
  node_cache_service["Media Cache Service"]
  node_cache_db[("Media Cache")]
end

node_client(("MCP Client"))

node_client -.->|"starts server"| node_launcher
node_launcher -->|"spawns Python"| node_server
node_client -->|"sends MCP requests"| node_server
node_server -.->|"dispatches tools"| node_ads_tools
node_ads_tools -->|"requests ads"| node_scrape
node_scrape -->|"fetches ad data"| node_ads_api
node_server -.->|"dispatches tools"| node_image_analysis
node_image_analysis -->|"checks and stores"| node_cache_service
node_server -.->|"dispatches tools"| node_video_analysis
node_video_analysis -->|"checks and stores"| node_cache_service
node_video_analysis -->|"uploads and analyzes"| node_gemini
node_server -.->|"dispatches tools"| node_cache_tools
node_cache_tools -->|"manages cache"| node_cache_service
node_cache_service -->|"reads and writes"| node_cache_db

click node_launcher "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/index.js"
click node_server "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py"
click node_ads_tools "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py"
click node_scrape "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/scrapecreators_service.py"
click node_image_analysis "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py"
click node_video_analysis "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py"
click node_cache_tools "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py"
click node_cache_service "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/media_cache_service.py"
click node_cache_db "https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/media_cache_service.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_launcher,node_server,node_client toneBlue
class node_ads_tools,node_scrape,node_ads_api toneAmber
class node_image_analysis,node_video_analysis,node_gemini toneMint
class node_cache_tools,node_cache_service,node_cache_db toneRose
```

## Components

### MCP Runtime

- [Node Launcher](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/index.js): `index.js`
- [MCP Server](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py): `mcp_server.py`

### Ad Retrieval

- [Ad Tools](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py): `mcp_server.py`
- [Ads API Service](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/scrapecreators_service.py): `src/services/scrapecreators_service.py`
- **ScrapeCreators API**

### Media Analysis

- [Image Analysis](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py): `mcp_server.py`
- [Video Analysis](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py): `mcp_server.py`
- **Gemini Video AI**

### Media Cache

- [Cache Tools](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/mcp_server.py): `mcp_server.py`
- [Media Cache Service](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/media_cache_service.py): `src/services/media_cache_service.py`
- [Media Cache](https://github.com/proxy-intell/google-ads-library-mcp/blob/main/src/services/media_cache_service.py): `src/services/media_cache_service.py`

### Other components

- **MCP Client**

## Connections

- MCP Client → Node Launcher: starts server (evidence: `readme.md`)
- Node Launcher → MCP Server: spawns Python (evidence: `index.js`)
- MCP Client → MCP Server: sends MCP requests (evidence: `readme.md`)
- MCP Server → Ad Tools: dispatches tools (evidence: `mcp_server.py`)
- Ad Tools → Ads API Service: requests ads (evidence: `mcp_server.py`)
- Ads API Service → ScrapeCreators API: fetches ad data (evidence: `src/services/scrapecreators_service.py`)
- MCP Server → Image Analysis: dispatches tools (evidence: `mcp_server.py`)
- Image Analysis → Media Cache Service: checks and stores (evidence: `mcp_server.py`)
- MCP Server → Video Analysis: dispatches tools (evidence: `mcp_server.py`)
- Video Analysis → Media Cache Service: checks and stores (evidence: `mcp_server.py`)
- Video Analysis → Gemini Video AI: uploads and analyzes (evidence: `mcp_server.py`)
- MCP Server → Cache Tools: dispatches tools (evidence: `mcp_server.py`)
- Cache Tools → Media Cache Service: manages cache (evidence: `mcp_server.py`)
- Media Cache Service → Media Cache: reads and writes (evidence: `src/services/media_cache_service.py`)
