Which integrations are available for this server?

Provides tools for inspecting, optimizing, and managing Google Ads campaigns, ad groups, keywords, RSA ads, assets, negative keywords, and analytics with deterministic execution safeguards. Provides tools for retrieving Google Cloud Logging logs and W3C distributed traces to monitor Google Ads API calls, latency breakdowns, and process health.

How do I use Safe Google Ads FastMCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Safe Google Ads FastMCP Server audit my search campaign for wasted spend and suggest negative keywords" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Safe Google Ads FastMCP Server

by Azhy34

Overview Schema Source Related Servers Discussions Admin

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, 38 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:

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.
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.
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: Google Ads MCP

🏗️ 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" }
    }
  ]
}

🧰 38 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	`get_campaigns`, `get_campaign_details`, `step_bid_threshold`, `set_campaign_daily_budget`, `toggle_campaign_status`	Campaign CPC ceilings stepped strictly by `±0.05 EUR`.
👥 Groups & Keywords	`get_ad_groups`, `get_ad_group_keywords`, `set_keyword_status`, `auto_fix_collisions_and_dupes`	Quality score audits, cross-campaign collision fixer.
✍️ RSA Ads & Facades	`get_campaign_ads`, `deploy_golden_rsa`	Smart Facade: Enforces 15 headlines & 4 descriptions, atomic rotation (pauses oldest ad atomically).
🧩 Google Assets	`create_price_asset`, `sync_price_extension`, `link_asset_to_entity`, `get_assets_diversity`, `get_assets_performance`	Price extensions, image assets, sitelinks, and performance labeling.
🧹 Negative Shields	`apply_negative_shield`, `mine_search_terms_and_harvest_negatives`, `remove_negative_keyword`	E-commerce waste harvesting and multi-country negative keyword sets.
📈 Analytics & GA4	`get_daily_performance`, `get_impression_share_loss`, `search_keyword_ideas`	Keyword Planner discovery 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.
🔍 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.

🚀 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. Test in Official MCP Inspector

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

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

4. 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"
    }
  }
}

📊 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 issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Upfixe Ads AOAuth
com.upfixe.app
Upfixe is the autonomous PPC engine built for AI agents. With Upfixe's Model Context Protocol (MCP) server, your AI assistant can research keywords, draft responsive search ads, structure ad groups, publish campaigns, and pull cross-network analytics across both Google Ads and Microsoft Advertising (Bing Ads). Features enterprise-grade token encryption (AES-256-GCM) and strict safety guardrails (auto-paused deployments, daily budget caps, O&O syndication filters).
E-commerce & Retail Marketing
342
LoomaScale AdsOAuth
com.loomascale
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Marketing Social Media App Automation
11
AdWhiz — Google & Meta Ads MCP ServerOAuth
io.github.iamzifei
Google & Meta Ads management with 100+ tools. Audit, create, and optimize campaigns.
Marketing App Automation
2
Adwarp
io.github.adwarp-dev
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Marketing App Automation
123

Related MCP Servers

Complete Google Ads API v21
Marketing App Automation
grantweston
A
license
Not graded
quality
D
maintenance
Provides full Google Ads API v21 access with 40+ tools for creating, optimizing, and managing campaigns, ad groups, keywords, extensions, and bidding strategies through natural language commands.
Updated a year ago (2025-09-02 02:31 UTC)
26
MIT
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.
Updated 3 months ago (2026-07-21 13:35 UTC)
3
-
mcp-google_ads
Marketing Search
pipeworx-io
A
license
Not graded
quality
B
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.
Updated 23 days ago (2026-09-26 18:56 UTC)
11 npm
MIT
Complete Google Ads API v21
Marketing E-commerce & Retail Command Line
DS-WEB1
A
license
Not graded
quality
B
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.
Updated 2 months ago (2026-09-02 15:14 UTC)
MIT