Google Ads MCP Server

# Google Ads MCP Server - Architecture Document ## Overview This document describes the architecture of the Google Ads MCP (Model Context Protocol) server. It is designed for two audiences: 1. **Developers** who need to understand the codebase structure and extend functionality 2. **Product Managers** who need to understand capabilities and how components interact --- ## What is MCP? MCP (Model Context Protocol) is a standard for connecting AI assistants (like Claude) to external tools and data sources. Think of it as a "plugin system" that lets Claude interact with Google Ads. MCP defines three primitives: | Primitive | What It Does | Analogy | |-----------|--------------|---------| | **Resources** | Read-only data Claude can access | Like reading a document | | **Tools** | Actions Claude can perform | Like clicking a button | | **Prompts** | Pre-defined workflow templates | Like a checklist or recipe | --- ## Architecture Diagram ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Google Ads MCP Server │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ │ │ KNOWLEDGE │ │ MEMORY │ │ PROMPTS │ │ │ │ (Resources) │ │ (Resources+Tools)│ │ (Workflows) │ │ │ │ │ │ │ │ │ │ │ │ • App Context │ │ R: Change Log │ │ • weekly_review │ │ │ │ • User Archetypes│ │ R: Report History│ │ • optimize_campaign │ │ │ │ • Keyword Research│ │ R: Decisions │ │ • keyword_expansion │ │ │ │ │ │ R: Insights │ │ • budget_reallocation│ │ │ │ │ │ T: log_decision │ │ • new_campaign_setup │ │ │ │ │ │ T: record_learning│ │ • diagnose_drop │ │ │ │ │ │ T: save_snapshot │ │ │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ ACTIONS (Tools) │ │ │ │ │ │ │ │ Campaigns Ad Groups Ads Keywords Reports │ │ │ │ ────────── ───────── ────────── ────────── ────────── │ │ │ │ • list • list • list • list • campaign │ │ │ │ • get • create • create • add • keyword │ │ │ │ • create • update • update • update_bid • search │ │ │ │ • update • status • pause • metrics │ │ │ │ • status │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────┼─────────────────────────────┐ │ │ │ GOVERNANCE │ │ │ │ │ (Approval Layer) ▼ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Permissions │ │ Approval │ │ Limits │ │ │ │ │ │ Tiers │ │ Workflow │ │ & Bounds │ │ │ │ │ │ 0,1,2,3 │ │ ask/approve │ │ max ±20% │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────┼─────────────────────────────┐ │ │ │ INFRASTRUCTURE │ │ │ │ │ ▼ │ │ │ │ config.py google_ads_client.py database │ │ │ │ (credentials) (API wrapper) (SQLite) │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────┐ │ Google Ads API │ └─────────────────┘ ``` --- ## Layer Descriptions ### 1. Knowledge Layer (Resources) **Purpose:** Provides static context about the business, product, and target audience. **Location:** `src/knowledge/` **For Developers:** - Resources are registered via `@server.list_resources()` and `@server.read_resource()` - Data is loaded from JSON files in `data/knowledge/` - Read-only; Claude cannot modify these **For Product Managers:** - This is where you configure WHO you're targeting and WHAT you're selling - Update these files to change Claude's understanding of your business - Examples: product descriptions, customer personas, keyword lists | Resource | URI | Description | |----------|-----|-------------| | App Context | `knowledge://app/context` | Product info, value props, target audiences | | User Archetypes | `knowledge://users/archetypes` | Customer personas, pain points, motivations | | Keyword Research | `knowledge://keywords/research` | Keyword lists, volumes, competition | --- ### 2. Actions Layer (Tools) **Purpose:** Executes operations in Google Ads. These are the "buttons" Claude can press. **Location:** `src/actions/` **For Developers:** - Tools are registered via `@server.tool()` decorator - Each tool wraps Google Ads API calls via `google_ads_client.py` - All modifications are logged to the Memory layer **For Product Managers:** - These are the capabilities Claude has to manage your ads - Tools are organized by Google Ads entity type - All changes are tracked in the change log | Module | Capabilities | |--------|--------------| | `campaigns.py` | List, create, update, pause/enable campaigns | | `ad_groups.py` | List, create, update ad groups | | `ads.py` | List, create responsive search ads, change status | | `keywords.py` | List, add, update bids, pause keywords | | `reports.py` | Pull performance reports (campaign, keyword, search terms) | --- ### 3. Memory Layer (Resources + Tools) **Purpose:** Tracks history and learnings over time. Gives Claude "memory" across sessions. **Location:** `src/memory/` **For Developers:** - Split into two parts: - `resources.py` - Read operations (what happened, what we learned) - `tools.py` - Write operations (log decisions, record insights) - Data persisted in SQLite database at `data/memory.db` **For Product Managers:** - This is how Claude remembers what it did and why - Enables trend analysis and learning from past performance - Creates an audit trail of all decisions | Component | Type | Description | |-----------|------|-------------| | Change Log | Resource | All modifications made to the account | | Report History | Resource | Saved performance snapshots for comparison | | Decision History | Resource | Past decisions with rationale | | Insights | Resource | Accumulated learnings | | `log_decision` | Tool | Record a decision and why it was made | | `record_learning` | Tool | Store an insight or learning | | `save_report_snapshot` | Tool | Save report data for future comparison | | `update_decision_outcome` | Tool | Record result of a past decision | --- ### 4. Prompts Layer (Workflows) **Purpose:** Pre-defined templates that guide Claude through complex, multi-step tasks. **Location:** `src/prompts/` **For Developers:** - Prompts are registered via `@server.list_prompts()` and `@server.get_prompt()` - Each prompt returns structured instructions for Claude - Can include required and optional arguments **For Product Managers:** - Think of these as "playbooks" for common tasks - Ensures consistency in how Claude approaches recurring work - Can be customized for your specific workflows | Prompt | Description | When to Use | |--------|-------------|-------------| | `weekly_review` | Comprehensive performance analysis | Every week | | `optimize_campaign` | Deep-dive into one campaign | When a campaign needs attention | | `keyword_expansion` | Research new keyword opportunities | Monthly or after new product launch | | `budget_reallocation` | Redistribute budget based on performance | Monthly or when hitting caps | | `new_campaign_setup` | Guided new campaign creation | Launching new campaigns | | `diagnose_performance_drop` | Investigate sudden performance decline | When metrics drop unexpectedly | --- ## Project Structure ``` google-ads/ ├── src/ │ ├── server.py # Main MCP server entry point │ ├── config.py # Configuration and credentials │ ├── google_ads_client.py # Google Ads API wrapper │ │ │ ├── knowledge/ # KNOWLEDGE LAYER │ │ ├── __init__.py │ │ ├── resources.py # MCP resource registration │ │ ├── app_context.py # Product/app information │ │ ├── user_archetypes.py # Customer personas │ │ └── keyword_research.py # Keyword data │ │ │ ├── actions/ # ACTIONS LAYER │ │ ├── __init__.py │ │ ├── campaigns.py # Campaign management tools │ │ ├── ad_groups.py # Ad group management tools │ │ ├── ads.py # Ad management tools │ │ ├── keywords.py # Keyword management tools │ │ └── reports.py # Reporting tools │ │ │ ├── memory/ # MEMORY LAYER │ │ ├── __init__.py │ │ ├── database.py # SQLite initialization │ │ ├── resources.py # Read operations (Resources) │ │ ├── tools.py # Write operations (Tools) │ │ ├── change_log.py # Change tracking logic │ │ ├── report_history.py # Report storage logic │ │ ├── decisions.py # Decision tracking logic │ │ └── learnings.py # Insights storage logic │ │ │ ├── prompts/ # PROMPTS LAYER │ │ ├── __init__.py │ │ └── workflows.py # Workflow prompt definitions │ │ │ └── governance/ # GOVERNANCE LAYER │ ├── __init__.py │ ├── permissions.py # Permission tier definitions │ ├── approval.py # Approval workflow logic │ ├── limits.py # Autonomy limits │ └── config.py # User configuration │ ├── data/ │ ├── knowledge/ # Knowledge JSON files │ │ ├── app_context.json │ │ └── archetypes.json │ └── memory.db # SQLite database (auto-created) │ ├── memory-bank/ │ ├── architecture.md # This document │ ├── governance.md # Autonomy & approval framework │ └── implementation-plan.md # Phased build plan │ ├── pyproject.toml └── README.md ``` --- ## Data Flow ### How Claude Uses the MCP Server ``` ┌─────────┐ ┌─────────────┐ ┌──────────────────┐ ┌────────────┐ │ User │────▶│ Claude │────▶│ MCP Server │────▶│ Google Ads │ │ │ │ │ │ │ │ API │ └─────────┘ └─────────────┘ └──────────────────┘ └────────────┘ │ │ │ 1. Read Resources │ │◀─────────────────────│ (Knowledge, Memory) │ │ │ 2. Execute Tools │ │─────────────────────▶│ (Actions, Memory writes) │ │ │ 3. Follow Prompts │ │◀─────────────────────│ (Workflow guidance) ``` ### Example: Weekly Review Workflow 1. **User:** "Do a weekly review" 2. **Claude:** Loads `weekly_review` prompt 3. **Claude:** Reads `memory://changes/recent` (what changed this week) 4. **Claude:** Reads `memory://insights` (accumulated learnings) 5. **Claude:** Calls `get_campaign_report` tool (last 7 days) 6. **Claude:** Reads `memory://reports/history` (previous week's data) 7. **Claude:** Analyzes and presents findings 8. **Claude:** Calls `record_learning` if new insights found 9. **Claude:** Calls `save_report_snapshot` to save this week's data --- ## Key Design Decisions ### Why Split Memory into Resources + Tools? - **Resources** = Read-only context (change history, past reports, insights) - **Tools** = Write operations (log decision, record learning) This aligns with MCP semantics where Resources are for context and Tools are for actions. ### Why Add a Prompts Layer? Without prompts, Claude must improvise workflows each time. Prompts ensure: - Consistent approach to recurring tasks - Best practices are followed - All relevant data sources are consulted - Actions are properly documented ### Why Local SQLite for Memory? - Simple, no external dependencies - Works offline - Easy to backup (single file) - Sufficient for typical usage patterns --- ## Governance & Autonomy The agent operates under a governance framework that controls what actions it can take independently vs. what requires human approval. **Full details:** See [governance.md](governance.md) ### Permission Tiers (Summary) | Tier | Behavior | Examples | |------|----------|----------| | **Tier 0: Read Only** | Always allowed | View campaigns, pull reports | | **Tier 1: Suggest** | Agent recommends, human executes manually | Rarely used; user preference | | **Tier 2: Approve** | Agent prepares, human approves, agent executes | Budget, campaigns, bids, keywords (default) | | **Tier 3: Autonomous** | Agent executes and reports | Record learnings, save snapshots | **Default:** All modification actions start at **Tier 2** (approve before execute). ### Key Principles 1. **All modifications are logged** - Complete audit trail in the changelog 2. **Approval by default** - All changes require your approval initially 3. **Human controls tier promotion** - Agent can never promote itself; you must explicitly grant higher permissions 4. **Locked actions** - Some actions (budget, bid strategy) stay at Tier 2 permanently 5. **Limits apply** - Even autonomous actions have bounds (e.g., max ±20% bid change) ### For Developers - Each tool must declare its permission tier - Tools must call `log_change()` with approval status - Approval workflow is handled by the governance layer before tool execution ### For Product Managers - You control what the agent can do independently - Start conservative, grant more autonomy as you build trust - Budget decisions always stay under your control - Full audit trail available for compliance --- ## Extending the System ### Adding a New Tool 1. Create or update a file in `src/actions/` 2. Define function with `@server.tool()` decorator 3. Call `log_change()` to record the action 4. Register in `src/actions/__init__.py` ### Adding a New Resource 1. Add to `@server.list_resources()` handler 2. Add read logic to `@server.read_resource()` handler 3. Store data in appropriate location (JSON file or database) ### Adding a New Prompt 1. Add prompt definition in `src/prompts/workflows.py` 2. Include in `list_prompts()` return value 3. Add handler case in `get_prompt()` --- ## Glossary | Term | Definition | |------|------------| | **MCP** | Model Context Protocol - standard for AI tool integration | | **Resource** | Read-only data source in MCP | | **Tool** | Callable action in MCP | | **Prompt** | Pre-defined workflow template in MCP | | **RSA** | Responsive Search Ad - Google Ads ad format | | **ROAS** | Return on Ad Spend - revenue / ad cost | | **CPA** | Cost Per Acquisition - cost / conversions |