Skip to main content
Glama
Sign In
Safe Google Ads FastMCP Server

Safe Google Ads FastMCP Server

by Azhy34
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🛡️ Safe Google Ads FastMCP Server

Enterprise-grade FastMCP server for the Google Ads API. Empowers autonomous AI agents (Claude Code, Antigravity, Cursor) to safely inspect, optimize, and manage live search campaigns with two-layer deterministic execution shields, 59 purpose-built tools, and W3C distributed tracing.

License: MIT Python 3.10+ FastMCP Observability: W3C Trace

⚡ The Problem: Why Direct MCP Connection is a Hallucination

Most agent demos assume a naive architecture: LLM ➔ Generic MCP ➔ Production API.

In high-stakes enterprise domains like advertising, this pattern is dangerous:

  1. Unbounded Financial Blast Radius: An unconstrained agent can step a bid by 5.00 EUR instead of 0.05 EUR, or mutate 5 campaigns simultaneously, burning monthly budgets in minutes.

  2. Context Window Exhaustion: Exposing Google's 500+ raw gRPC methods bloats prompt context by 30,000+ tokens, inducing hallucinated arguments and non-deterministic tool picking.

  3. The "AI Black Box" Fallacy: Over standard stdio transports, client-level OpenTelemetry context is dropped. When a tool call times out or fails, engineers have zero visibility into whether the delay came from local Python logic, DNS, or Google's upstream servers.

Google’s official Google Ads MCP server is strictly read-only for this exact reason. To grant an autonomous agent write capabilities, you must insert an enforced deterministic boundary.

Related MCP server: mcp-google_ads

🏗️ High-Level Architecture

┌────────────────────────────────────────────────────────────────────────┐
│             AI Agent Client (Claude Code / Antigravity / Cursor)        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ 1. tools/call (JSON-RPC over stdio)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             Safe Google Ads FastMCP Gateway Server (server.py)         │
│                                                                        │
│   [ LAYER 1: Two-Layer Pydantic Execution Shield (shield/) ]           │
│   • Input boundary validation: Bounded bid ceilings (0.10 - 3.00 EUR)  │
│   • Fixed stepping increments (±0.05 EUR strictly enforced)             │
│   • Bad input is cut off early: returns REQUEST_REJECTED (0 API cost)  │
│                                                                        │
│   [ PREFLIGHT GATEKEEPER (shield/preflight.py) ]                       │
│   • Ad tools refuse execution until preflight_log_check passes         │
│   • Audits tool health, unlogged manual changes & process anomalies    │
│                                                                        │
│   [ LAYER 2: W3C Distributed Tracing & gRPC Interceptor ]              │
│   • Generates autonomous session_id & W3C trace_id per execution       │
│   • Custom gRPC Client Interceptor captures upstream Google request_id │
│   • Measures exact latency breakdown: Upstream API vs Local Code       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ 2. Mutate / Query Stream (gRPC v24)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│              Google Ads API v24 (Google Cloud Infrastructure)           │
│   CampaignService • AdGroupService • AssetService • CriterionService   │
└────────────────────────────────────────────────────────────────────────┘

🔬 Benchmark: Real-Time Latency & Tracing Breakdown

Below is a live distributed trace extracted via get_cloud_trace showing complete sub-millisecond execution observability for a single Smart Facade call (audit_campaign_4level_shield).

Notice how the single high-level tool coordinates 4 distinct upstream gRPC queries to Google Ads API while tracking exact network latency vs local execution overhead:

Parent Tool Span: tools/call audit_campaign_4level_shield [3378.7 ms]
├── 1. GoogleAdsService/Search (Campaign Level)           [1334.6 ms] ━━━━━━━━━━━━
├── 2. GoogleAdsService/Search (AdGroups & Bids)          [ 375.4 ms]             ━━━━
├── 3. GoogleAdsService/Search (RSAs & 15/4 Matrix)       [ 838.0 ms]                 ━━━━━━━━
└── 4. GoogleAdsService/Search (Negative Keywords Shield) [ 397.3 ms]                         ━━━━

Sanitized Trace Payload (get_cloud_trace):

{
  "trace_id": "a30661d140600f1b54cde6c3d1fc8cc1",
  "total_ms": 3378.7,
  "google_ads_api_calls": 4,
  "google_ads_api_ms": 2945.3,
  "own_code_ms": 433.4,
  "latency_breakdown": {
    "network_grpc_wait": "87.2%",
    "local_fastmcp_shield": "12.8%"
  },
  "spans": [
    {
      "span_id": "9f42e8ddf09f0132",
      "parent_span_id": null,
      "name": "tools/call audit_campaign_4level_shield",
      "duration_ms": 3378.7,
      "labels": {
        "tool": "audit_campaign_4level_shield",
        "action_type": "READ",
        "gcp.project_id": "safe-ads-prod",
        "operator": "[REDACTED]",
        "session_id": "20261019T141746Z-7acf",
        "sla_status": "DEGRADED"
      }
    },
    {
      "span_id": "c13ea22dda5f6e88",
      "parent_span_id": "9f42e8ddf09f0132",
      "name": "GoogleAdsService/Search (Campaign Level)",
      "duration_ms": 1334.6,
      "labels": { "rpc.system": "grpc", "rpc.grpc.status_code": "0" }
    },
    {
      "span_id": "ce45cd75502167c2",
      "parent_span_id": "9f42e8ddf09f0132",
      "name": "GoogleAdsService/Search (AdGroups & Bids)",
      "duration_ms": 375.4,
      "labels": { "rpc.system": "grpc", "rpc.grpc.status_code": "0" }
    },
    {
      "span_id": "3aac0efda8cd5253",
      "parent_span_id": "9f42e8ddf09f0132",
      "name": "GoogleAdsService/Search (RSAs & 15/4 Matrix)",
      "duration_ms": 838.0,
      "labels": { "rpc.system": "grpc", "rpc.grpc.status_code": "0" }
    },
    {
      "span_id": "47f195265a727044",
      "parent_span_id": "9f42e8ddf09f0132",
      "name": "GoogleAdsService/Search (Negative Keywords Shield)",
      "duration_ms": 397.3,
      "labels": { "rpc.system": "grpc", "rpc.grpc.status_code": "0" }
    }
  ]
}

🧰 59 Custom FastMCP Tools Catalog

The tools mirror Google Ads operational hierarchy, split into granular objects and transactional Smart Facades:

Operational Level

Key MCP Tools

Responsibilities

🚦 Gate & Health

preflight_log_check, analyze_tool_health

Mandatory pre-flight lock; anomaly & error spike audit.

📢 Campaigns & Bids

create_search_campaign, create_shopping_campaign, set_campaign_location, get_campaigns, get_campaign_details, step_bid_threshold, set_campaign_daily_budget, toggle_campaign_status

Automated Search campaign creation with clean search networks, dayparting & criteria; CPC ceilings stepped strictly by ±0.05 EUR. Shopping campaigns on the Merchant Center feed (always paused, dry run first) and country on/off inside an existing campaign (never the last one).

👥 Groups & Keywords

create_ad_group, add_ad_group_keywords, get_ad_groups, get_ad_group_keywords, set_keyword_status, set_ad_group_status, auto_fix_collisions_and_dupes

Hub & Spoke ad group deployment, positive exact/phrase keyword batches, cross-group collision fixer. Guarded status switch for a whole ad group (never the last enabled one, never a half-built one).

✍️ RSA Ads & Facades

get_campaign_ads, deploy_golden_rsa, set_ad_status

Smart Facade: Enforces 15 headlines & 4 descriptions, Dynamic Keyword Insertion (DKI), in-place mutation via AdService.mutate_ads, and status toggles with last-active ad safeguards.

🧩 Google Assets

create_price_asset, create_image_asset, get_assets_associations, get_campaign_images, sync_price_extension, preview_sitelink_assets, create_sitelink_assets, create_callout_assets, create_structured_snippet_asset, link_asset_to_entity, unlink_asset_from_entity, get_assets_diversity, get_assets_performance

Price extensions, Sitelinks, Callouts, Structured Snippets with Google approved headers, and asset performance labeling. Own-site images cropped to 1.91:1 / 1:1 and linked per ad group as AD_IMAGE; filtered reads of what a campaign or ad group shows.

🧹 Negative Shields

apply_negative_shield, sync_shared_negative_list, mine_search_terms_and_harvest_negatives, add_negative_keywords, remove_negative_keyword

E-commerce waste harvesting, multi-country negative keyword sets, and atomic shared negative list sync.

🎯 Conversions & Tracking

check_enhanced_conversions_status, set_conversion_action_goal, upload_click_conversion

Enhanced Conversions audit (Customer Data Terms, DMA compliance), Primary/Secondary goal steering for Smart Bidding, and hashed offline conversion upload.

💳 Billing & Merchant Link

get_google_ads_invoices, check_merchant_center_link, check_shopping_readiness, audit_geo_physical_locations, get_demand_gen_currency_floor

Official PDF invoices retrieval, Merchant Center product link audits, physical geo leakage discovery, and currency budget floors. Two-sided Shopping readiness (Ads + Merchant Center).

📈 Analytics & GA4

get_daily_performance, get_impression_share_loss, search_keyword_ideas

Keyword Planner discovery, Search Impression Share loss tracking, and spend vs GA4 dwell-time metrics.

🔭 Observability

get_cloud_logs, get_cloud_trace, verify_changes_logged, evaluate_agent_process

Cloud Logging inspection, W3C trace breakdown, and process evals.

🧠 Autonomous Agent Skills & Playbooks (skills/)

While MCP tools provide the execution layer (the hands), these bundled Agent Skills provide the deterministic business playbook (the brain) for autonomous coding agents (Claude Code, Antigravity, Cursor):

Skill Name

SOP Path

Playbook Description

🛡️ 4-Level Campaign Auditor

skills/google-ads-campaign-auditor/

Standard procedure for running Preflight gate checks and diagnosing campaign quality scores (100/100).

🪜 Deterministic Bid Ladder

skills/google-ads-bid-ladder/

Stepping CPC bid ceilings strictly by ±0.05 EUR on TARGET_SPEND campaigns with Impression Share guards.

✍️ 15/4 Golden RSA Writer

skills/google-ads-rsa-writer/

Enforces 15 headlines, 4 descriptions, Dynamic Keyword Insertion (DKI) pinned to Position 1, and atomic rotation.

🏢 Hub & Spoke Ad Groups

skills/google-ads-hub-and-spoke-adgroups/

Structuring consolidated Search campaigns into focused Hub & Spoke ad groups with dedicated category landings.

🎯 Conversion Tracking & Goals

skills/google-ads-conversion-tracking/

Enhanced Conversions audit, steering Smart Bidding via Primary/Secondary goals, and offline conversion uploads.

🔍 Search Terms & GA4 Miner

skills/google-ads-search-terms-miner/

Cross-referencing ad spend with GA4 on-site engagement to harvest negative keywords and eliminate budget leaks.

🛒 Shopping Campaigns

skills/google-ads-shopping-campaigns/

Feed-based Standard Shopping: readiness on both sides, deliberate product choice, dry run, creation always paused, verification.

🖼️ Image Assets

skills/google-ads-image-assets/

Own-site images per ad group: dry-run the crop, create once, link as AD_IMAGE, read back with narrow filters.

🌍 Geo Targeting

skills/google-ads-geo-targeting/

Targeting overview, budget-leak audit, country on/off without ever leaving a campaign with no location.

🎛️ FastMCP Manager & Orchestrator

skills/google-ads-mcp-manager/

Master multi-level orchestrator: 5-stage lifecycle, 4 account invariants, tool extension protocol, and watchdog SOP rules.

🚀 Quickstart & Installation

1. Clone & Install

git clone https://github.com/Azhy34/safe-google-ads-mcp.git
cd safe-google-ads-mcp
pip install -r requirements.txt

2. Configure Credentials (Zero-Leak)

Copy the template and provide your Google Ads developer tokens:

cp .env.example .env

3. Set your business policy

The code carries no account, coupon, host or campaign name: those are data in a policy file (neutral defaults ship in config/policy.json). Tools that need an identity or an allowed host refuse until you set it:

cp config/policy.json config/policy.local.json    # git-ignored; edit it: accounts, URL rules, allowed hosts, ...

See docs/POLICY.md for every key.

4. Test in Official MCP Inspector

You can inspect schemas and test tools interactively without spending LLM tokens:

npx @modelcontextprotocol/inspector --web --config .mcp.json

5. Connect to Claude Code / Desktop

Add the server entry to your client configuration:

{
  "mcpServers": {
    "safe-google-ads-mcp": {
      "command": "python",
      "args": ["/path/to/safe-google-ads-mcp/server.py"],
      "cwd": "/path/to/safe-google-ads-mcp"
    }
  }
}

6. Run the offline test suite

python -m unittest discover -s tests

The suite uses a fictional advertiser (tests/policy_test.json) and never touches the network or your policy.

🏢 Business Policy: one codebase, your rules

Everything that belongs to your business sits in config/policy.local.json (or the file named by MCP_POLICY_FILE): your accounts, which hosts must carry a coupon and which must not, the words that never appear in your ads, the hosts your sitelinks and images may use, your Shopping campaign prefix, the countries you deliver to. A rule broken in a request is refused by the shield (REQUEST_REJECTED) before any call to Google. See docs/POLICY.md.

📝 Changelog

See CHANGELOG.md: 1.1.0 adds set_ad_group_status, set_campaign_location, create_image_asset, create_shopping_campaign and check_shopping_readiness (59 tools), the policy layer and three skills.

📊 Live SDLC Orchestration in Jira

This framework was designed, decomposed, and built autonomously using our open-source Jira Cloud engine (jira-cloud-automation-shield):

  • Public Jira Epic: [KAN-30] Safe Google Ads FastMCP Shield & Distributed Tracing Framework

  • Live Kanban Board: Atlassian Cloud Kanban Board

  • Automated Audit Comments: Every task transition across To Do ➔ In Progress ➔ Done is stamped with correlation trace_id.

📄 License

MIT License. Created by Mykhail Azhyshchev.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google Ads MCP

    tolkozin
    F
    license
    A
    quality
    D
    maintenance
    Enables AI agents to manage Google Ads campaigns (Search and UAC) through natural language, with read tools always available and guarded write operations for budgets, campaigns, ad groups, and keywords.
    3
    -

  • mcp-google_ads

    pipeworx-io
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to manage and analyze Google Ads campaigns through tools for listing campaigns, retrieving settings, performance metrics, ad groups, and running custom GAQL queries.
    454 npm
    MIT

  • Complete Google Ads API v21

    DS-WEB1
    A
    license
    Not graded
    quality
    C
    maintenance
    Complete Google Ads API v21 MCP server with 40+ fully implemented tools for campaign, ad group, keyword, extension, and portfolio bidding management, enabling AI assistants to create, optimize, and manage Google Ads campaigns through natural language commands.
    MIT
  • Marvento Ads MCP

    Marvento Ads MCPofficial

    MarventoCapital
    A
    license
    B
    quality
    B
    maintenance
    Enables AI agents to build and run Google Ads campaigns with write tools for campaigns, ad groups, ads, and assets, plus one-command VPS deployment for remote access.
    23
    Apache 2.0