Google Ads MCP Server
Provides comprehensive tools for Google Ads campaign analysis, optimization, and management, including campaign performance metrics, keyword analysis, search terms reporting, budget updates, campaign status control, and AI-powered recommendations through the Google Ads API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Ads MCP Server show me campaign performance for the last 7 days"
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.
Google Ads MCP Server
A comprehensive Model Context Protocol (MCP) server for Google Ads API integration, enabling AI assistants like Claude, ChatGPT, and Gemini to analyze, manage, and optimize Google Ads campaigns through natural language conversations.
Table of Contents
Related MCP server: Google Ads MCP Server
Overview
The Google Ads MCP Server transforms how you interact with Google Ads by providing a natural language interface powered by Model Context Protocol. Instead of navigating complex dashboards or writing custom API code, you can analyze campaigns, optimize keywords, and manage budgets through simple conversations with AI assistants.
What is MCP?
Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect with external data sources and tools. This server implements MCP to bridge AI assistants with the Google Ads API.
Key Benefits:
Natural Language Interface: Ask questions and give commands in plain English
Multi-Platform Support: Works with Claude Desktop, ChatGPT, Gemini, and other MCP-compatible AI assistants
Comprehensive Coverage: From basic reporting to advanced campaign management
Secure: OAuth 2.0 authentication with best-practice credential management
Extensible: Modular architecture supporting 161 planned tools across 14 functional domains
Features
Current Features (v1)
The current stable release (v1) provides 10 essential tools for Google Ads analysis and management:
Analysis & Reporting
List all accessible Google Ads accounts
Campaign performance analysis with filtering and date ranges
Keyword performance tracking (quality scores, positions, conversions)
Search terms discovery (actual queries triggering ads)
Ad group performance metrics
Google's AI-powered optimization recommendations
Campaign Management
Update campaign daily budgets
Pause or enable campaigns
Execute custom GAQL queries for advanced analysis
Roadmap (v2)
The v2 roadmap expands the server to 161 tools across 14 functional domains, covering approximately 85% of the Google Ads API surface area for campaign management and optimization.
Planned Capabilities:
Domain | Tools | Description |
Campaign Management | 23 | Create, update, delete campaigns (all 9 types) |
Ad & Creative Management | 18 | Responsive Search Ads, Display, Video, Performance Max |
Keyword Management | 15 | Bulk operations, negative keywords, match types |
Bidding & Optimization | 12 | Portfolio strategies, bid adjustments, automation |
Audience Management | 14 | Remarketing, Customer Match, custom audiences |
Conversion Tracking | 11 | Setup, offline imports, attribution |
Advanced Reporting | 25 | Geographic, demographic, competitive insights |
Batch Operations | 8 | Bulk uploads, mass updates, CSV import/export |
Extensions & Assets | 12 | Sitelinks, callouts, structured snippets |
Shopping & PMax | 10 | Product feeds, Performance Max campaigns |
Local & App Campaigns | 8 | Store visits, app installs, local inventory |
Automation | 10 | Automated rules, smart bidding, scripts integration |
Insights & Analytics | 8 | Forecasting, auction insights, change history |
Labels & Organization | 7 | Campaign labels, asset groups, organization |
Total: 161 tools covering end-to-end campaign lifecycle management.
See documentation/EXECUTIVE_SUMMARY.md and documentation/COMPLETE_TOOLS_DOCUMENTATION.md for the roadmap and detailed tool coverage.
Quick Start
Get up and running in 5 minutes:
Prerequisites
Python 3.10 or higher
Google Ads account with active campaigns
Google Ads API Developer Token (apply here)
Installation
Clone the repository:
git clone https://github.com/johnoconnor0/google-ads-mcp.git cd google-ads-mcpInstall dependencies:
pip install -r requirements.txtGenerate OAuth credentials (see Google Ads API Setup for details):
python generate_refresh_token.pyConfigure Claude Desktop (or your preferred AI assistant):
Edit
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or%APPDATA%\Claude\claude_desktop_config.json(Windows):{ "mcpServers": { "google-ads": { "command": "python", "args": ["/absolute/path/to/google_ads_mcp.py"], "env": {} } } }Restart Claude Desktop and start asking questions about your Google Ads accounts!
First Steps
Once configured, try these commands in Claude Desktop:
"Initialize my Google Ads connection with these credentials..."
"Show me all my Google Ads accounts"
"Analyze campaign performance for the last 30 days"
"Which keywords have the lowest quality scores?"See Usage Examples for more.
Quick Verify
Use this sequence to validate a clean clone before publishing or opening a PR:
python -m pip install --upgrade pip
pip install -e .[dev]
ruff check tests scripts generate_refresh_token.py`nblack --check tests scripts generate_refresh_token.py`nflake8 --max-line-length=120 tests scripts generate_refresh_token.py`nmypy --explicit-package-bases tests
pytest
python -m buildSetup & Installation
Prerequisites
Required
Python: Version 3.8 or higher
python --version # Should output 3.10 or higherGoogle Ads Account: Active account with campaigns
Google Ads API Access: Developer token (may take 24-48 hours for approval)
OAuth 2.0 Credentials: Client ID and Client Secret from Google Cloud Console
Optional
MCC Account: For managing multiple client accounts
Redis: For distributed caching (optional, defaults to in-memory cache)
Google Ads API Setup
Step 1: Apply for Developer Token
Sign in to your Google Ads account
Navigate to Tools & Settings → Setup → API Center
Apply for a developer token
Wait for approval (typically 24-48 hours)
Important: Test developer tokens work immediately but have limitations
Resource: Google Ads API Developer Token Guide
Step 2: Create OAuth 2.0 Credentials
Go to Google Cloud Console
Create a new project (or select existing)
Enable the Google Ads API:
Navigation → APIs & Services → Library
Search for "Google Ads API"
Click "Enable"
Create OAuth credentials:
APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Choose Desktop app as application type
Name your OAuth client (e.g., "Google Ads MCP Server")
Click Create
Download your credentials or copy:
Client ID (ends with
.apps.googleusercontent.com)Client Secret
Resource: OAuth 2.0 Setup Guide
Step 3: Generate Refresh Token
Use the provided utility script to generate a refresh token:
python generate_refresh_token.pyWhat this script does:
Opens a browser for Google authorization
You grant access to your Google Ads account
Generates a refresh token (long-lived credential)
Displays the refresh token to copy
Alternative manual method:
from google_auth_oauthlib.flow import InstalledAppFlow
CLIENT_ID = 'your-client-id.apps.googleusercontent.com'
CLIENT_SECRET = 'your-client-secret'
SCOPES = ['https://www.googleapis.com/auth/adwords']
flow = InstalledAppFlow.from_client_config(
{
"installed": {
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
}
},
scopes=SCOPES
)
credentials = flow.run_local_server(port=0)
print(f"Refresh Token: {credentials.refresh_token}")Important: Store your refresh token securely! It provides ongoing access to your Google Ads account.
Server Installation
Install Python Dependencies
Option 1: Install from requirements.txt (recommended):
pip install -r requirements.txtOption 2: Manual installation:
pip install google-ads>=25.0.0 mcp>=1.1.0 httpx>=0.27.0 pydantic>=2.0.0 google-auth-oauthlib>=1.0.0Optional dependencies (for advanced features):
# Caching with Redis
pip install redis>=5.0.0
# Export and reporting
pip install openpyxl>=3.1.2 reportlab>=4.0.0 matplotlib>=3.8.0Verify Installation
python -c "import google.ads.googleads, mcp, httpx, pydantic; print('All dependencies installed successfully!')"AI Integration
The Google Ads MCP Server can be integrated with multiple AI platforms:
Claude Desktop Integration
Recommended for: Most users, easiest setup
Locate configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add MCP server configuration:
{ "mcpServers": { "google-ads": { "command": "python", "args": ["/absolute/path/to/google_ads_mcp.py"], "env": {} } } }Replace
/absolute/path/to/google_ads_mcp.pywith the actual file path.Restart Claude Desktop for changes to take effect
Initialize the connection in Claude:
Initialize my Google Ads connection with these credentials: - Developer Token: YOUR_DEV_TOKEN - Client ID: YOUR_CLIENT_ID.apps.googleusercontent.com - Client Secret: YOUR_CLIENT_SECRET - Refresh Token: YOUR_REFRESH_TOKEN - Login Customer ID: YOUR_MCC_ID (optional, only if using MCC)
Resources:
ChatGPT Integration
Status: Experimental (MCP support via third-party tools)
ChatGPT does not natively support MCP as of December 2025. However, integration is possible via:
Option 1: MCP Bridge (if available)
Use an MCP-to-OpenAI API bridge
Configure the bridge to expose Google Ads MCP tools as OpenAI functions
Access via ChatGPT Plus with plugin support
Option 2: Custom GPT with API Wrapper
Create a web API wrapper around the MCP server
Build a Custom GPT with function calling to your API
Configure authentication and endpoints
Option 3: Use Claude Code or API
Run the MCP server with Claude Code (CLI)
Use Claude API to access the MCP tools programmatically
Integrate results into your ChatGPT workflow
Note: As ChatGPT's MCP support evolves, this section will be updated with native integration instructions.
Gemini Integration
Status: Experimental (MCP support via third-party tools)
Google's Gemini does not natively support MCP as of December 2025. However, integration is possible via:
Option 1: Vertex AI Function Calling
Deploy the MCP server as a Google Cloud Function or Cloud Run service
Use Vertex AI's function calling with Gemini
Map MCP tools to Gemini function definitions
Option 2: LangChain Integration
Use LangChain to create a bridge between Gemini and MCP tools
Define MCP tools as LangChain tools
Create a Gemini agent with MCP tool access
Option 3: Custom Integration
Build a REST API wrapper around the MCP server
Use Gemini API with function calling
Map Google Ads operations to function definitions
Resources:
Other MCP-Compatible Platforms
The server works with any MCP-compatible client. See the MCP Documentation for integration guides.
MCP Tool Reference
v1 Tools (10 Current Tools)
The current stable release provides these tools:
1. google_ads_initialize
Description: Initialize API connection with OAuth credentials.
Parameters:
{
"developer_token": "string (required)",
"client_id": "string (required)",
"client_secret": "string (required)",
"refresh_token": "string (required)",
"login_customer_id": "string (optional)"
}Example:
Initialize with:
- Developer Token: abc123...
- Client ID: 123456789.apps.googleusercontent.com
- Client Secret: xyz789...
- Refresh Token: YOUR_REFRESH_TOKEN
- Login Customer ID: 1234567890 (only for MCC accounts)Returns: Confirmation message with API version and accessibility check
2. google_ads_list_accounts
Description: List all accessible Google Ads accounts.
Parameters:
{
"response_format": "markdown | json (default: markdown)"
}Example:
"Show me all my Google Ads accounts"
"List accounts in JSON format"Returns: Account list with customer IDs, names, and descriptive names
3. google_ads_campaign_performance
Description: Get comprehensive campaign metrics with filtering and date ranges.
Parameters:
{
"customer_id": "string (required, 10 digits no hyphens)",
"date_range": "TODAY | YESTERDAY | LAST_7_DAYS | LAST_30_DAYS | etc. (default: LAST_30_DAYS)",
"campaign_status": "ENABLED | PAUSED | REMOVED (optional)",
"min_cost": "number (optional, in account currency)",
"limit": "number (default: 50, max: 100)",
"response_format": "markdown | json (default: markdown)"
}Example:
"Show campaign performance for the last 30 days for account 1234567890"
"Find campaigns with at least $100 in spend this month"
"Show only enabled campaigns for account 1234567890"Returns: Campaign metrics including impressions, clicks, cost, conversions, CTR, CPC, conversion rate
4. google_ads_keyword_performance
Description: Analyze keyword-level performance with quality scores and positions.
Parameters:
{
"customer_id": "string (required)",
"campaign_id": "string (optional)",
"date_range": "string (default: LAST_30_DAYS)",
"min_impressions": "number (optional)",
"limit": "number (default: 50)",
"response_format": "markdown | json"
}Example:
"Analyze keyword performance for campaign 12345"
"Show keywords with quality score below 5"
"Find keywords with the highest cost per conversion"Returns: Keyword metrics including quality score, average position, impressions, clicks, cost, conversions
5. google_ads_search_terms
Description: Get actual search queries that triggered your ads.
Parameters:
{
"customer_id": "string (required)",
"campaign_id": "string (optional)",
"date_range": "string (default: LAST_30_DAYS)",
"min_impressions": "number (default: 10)",
"limit": "number (default: 50)",
"response_format": "markdown | json"
}Example:
"What search terms triggered my ads in the last 30 days?"
"Find high-impression search terms with low CTR"
"Show search terms for campaign 67890"Returns: Search term, match type, impressions, clicks, cost, conversions, CTR
6. google_ads_ad_group_performance
Description: Analyze ad group-level metrics.
Parameters:
{
"customer_id": "string (required)",
"campaign_id": "string (optional)",
"date_range": "string (default: LAST_30_DAYS)",
"limit": "number (default: 50)",
"response_format": "markdown | json"
}Example:
"Show ad group performance for all campaigns"
"Find best-performing ad groups in campaign 12345"Returns: Ad group metrics including impressions, clicks, cost, conversions, CTR, CPC
7. google_ads_recommendations
Description: Get Google's AI-powered optimization suggestions.
Parameters:
{
"customer_id": "string (required)",
"recommendation_types": "array of strings (optional)",
"limit": "number (default: 20)",
"response_format": "markdown | json"
}Example:
"Show optimization recommendations for account 1234567890"
"What does Google suggest for improving my campaigns?"Returns: Recommendation type, impact estimate, suggested changes, rationale
8. google_ads_update_campaign_budget
Description: Modify campaign daily budget.
Parameters:
{
"customer_id": "string (required)",
"campaign_id": "string (required)",
"budget_amount_micros": "number (required, in micros)"
}Budget conversion: Multiply your budget by 1,000,000
$10.00 = 10,000,000 micros
$50.50 = 50,500,000 micros
$100.00 = 100,000,000 micros
Example:
"Set campaign 12345 budget to $75 per day"
"Increase budget for campaign 67890 to 100,000,000 micros ($100)"Returns: Confirmation with old and new budget values
9. google_ads_update_campaign_status
Description: Pause or enable campaigns.
Parameters:
{
"customer_id": "string (required)",
"campaign_id": "string (required)",
"status": "ENABLED | PAUSED (required)"
}Example:
"Pause campaign 12345"
"Enable campaign 67890"Returns: Confirmation with new status
10. google_ads_custom_query
Description: Execute custom GAQL (Google Ads Query Language) queries.
Parameters:
{
"customer_id": "string (required)",
"query": "string (required, valid GAQL query)",
"response_format": "markdown | json"
}Example:
"Execute this GAQL query: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000"Resources:
Returns: Query results in requested format
v2 Roadmap (161 Planned Tools)
The v2 implementation expands the server to 161 tools across 14 domains. Below is a summary of planned capabilities.
Campaign Management (23 tools)
Creation & Configuration:
Create campaigns (all 9 types: Search, Display, Shopping, Video, Performance Max, App, Local, Smart, Demand Gen)
Configure networks, locations, languages, start/end dates
Set up budgets (standard, shared, portfolio)
Configure bidding strategies
Updates & Optimization:
Modify campaign settings (name, networks, targeting)
Update location and language targeting
Manage device bid adjustments
Configure ad scheduling (dayparting)
Add campaign-level exclusions
Management:
Campaign experiments and A/B testing
Campaign labels and organization
Campaign deletion and archival
Status: Priority 2 - In active development
Ad & Creative Management (18 tools)
Ad Creation:
Responsive Search Ads (RSA) - up to 15 headlines, 4 descriptions
Expanded Text Ads (legacy)
Responsive Display Ads
Image ads (Display Network)
Video ads (YouTube, TrueView)
Performance Max asset groups
Ad Optimization:
Ad copy testing and analysis
Ad strength tracking
Creative asset management
Ad preview and testing
Status: Priority 2 - Planned
Keyword Management (15 tools)
Keyword Operations:
Bulk keyword addition (CSV import)
Keyword updates (match types, bids, status)
Keyword deletion
Negative keyword management
Negative keyword lists (shared)
Keyword Research & Analysis:
Keyword forecasting
Keyword suggestions
Match type optimization
Quality score tracking and improvement
Status: Priority 2 - Planned
Bidding & Optimization (12 tools)
Bidding Strategies:
Portfolio bidding strategies (Target CPA, Target ROAS, Maximize Conversions)
Bid adjustments (device, location, demographics, audiences, time-of-day)
Manual bidding configuration
Smart Bidding setup and monitoring
Optimization:
Automated rules and triggers
Bid simulation and forecasting
Performance optimization suggestions
Status: Priority 2 - Planned
Audience Management (14 tools)
Audience Creation:
Remarketing lists
Customer Match audience uploads
Custom audiences (interests, behaviors)
Similar audiences (lookalikes)
In-market and affinity audiences
Audience Targeting:
Apply audiences to campaigns/ad groups
Audience bid adjustments
Exclusion lists
Audience performance tracking
Status: Priority 3 - Planned
Conversion Tracking (11 tools)
Setup & Configuration:
Create conversion actions
Configure conversion tracking tags
Import offline conversions
Set up call tracking
Attribution & Analysis:
Multi-touch attribution models
Conversion value rules
Conversion lift studies
Cross-device conversion tracking
Status: Priority 3 - Planned
Advanced Reporting (25 tools)
Specialized Reports:
Geographic performance (country, region, city, postal code)
Demographic reports (age, gender, household income)
Time-based analysis (hour of day, day of week)
Device performance breakdown
Auction insights (competitive analysis)
Landing page performance
Call metrics and call tracking
Video performance (YouTube)
Shopping performance (product groups)
Report Customization:
Custom report builder
Period-over-period comparison
Trend analysis
Export to Excel/PDF/CSV
Scheduled reports
Status: Priority 2-3 - Partially planned
Batch Operations (8 tools)
Bulk Operations:
Batch campaign creation
Bulk keyword uploads (CSV)
Mass ad group creation
Bulk status changes
Batch budget updates
Import/Export:
Google Ads Editor CSV import
Export campaigns to CSV
Bulk change history
Status: Priority 3 - Planned
Extensions & Assets (12 tools)
Extension Types:
Sitelink extensions
Callout extensions
Call extensions
Location extensions
Price extensions
Structured snippet extensions
Promotion extensions
App extensions
Management:
Extension performance tracking
Asset library management
Extension scheduling
Extension bid adjustments
Status: Priority 3 - Planned
Shopping & Performance Max (10 tools)
Shopping Campaigns:
Product feed management
Product group creation
Shopping campaign optimization
Merchant Center integration
Performance Max:
Asset group creation
Audience signals
Performance tracking
Budget optimization
Status: Priority 3 - Planned
Local & App Campaigns (8 tools)
Local Campaigns:
Store visits tracking
Local inventory ads
Location-based bidding
Call tracking
App Campaigns:
App install campaigns
App engagement campaigns
Deep link configuration
In-app event tracking
Status: Priority 3 - Planned
Automation (10 tools)
Automated Rules:
Create custom rules
Schedule automated tasks
Trigger-based actions
Rule performance tracking
Smart Features:
Smart Bidding automation
Automated extensions
Dynamic ad customization
AI-powered optimization
Status: Priority 3 - Planned
Insights & Analytics (8 tools)
Forecasting:
Budget forecasting
Conversion forecasting
Seasonal trend analysis
Growth projections
Competitive Analysis:
Auction insights
Competitive benchmarking
Market share analysis
Change History:
Account change log
Performance change attribution
Rollback capabilities
Status: Priority 3 - Planned
Labels & Organization (7 tools)
Labels:
Campaign labels
Ad group labels
Keyword labels
Ad labels
Organization:
Folder structure management
Resource organization
Bulk label operations
Status: Priority 3 - Planned
For the complete implementation plan with technical details, see documentation/EXECUTIVE_SUMMARY.md.
Usage Examples
Claude Desktop Conversations
Account Overview
User: "Show me all my Google Ads accounts"
Claude: [Calls google_ads_list_accounts]
I can see you have 3 accessible Google Ads accounts:
1. Account 123-456-7890 (My Business)
2. Account 234-567-8901 (E-commerce Store)
3. Account 345-678-9012 (Client ABC)Campaign Analysis
User: "Analyze campaign performance for the last 30 days for my main account"
Claude: [Calls google_ads_campaign_performance with customer_id="1234567890"]
Here's the performance for your campaigns over the last 30 days:
Top Performers:
- Brand Campaign: $1,245 spent, 523 conversions, $2.38 CPA
- Shopping Campaign: $2,100 spent, 312 conversions, $6.73 CPA
Needs Attention:
- Generic Keywords: $850 spent, 12 conversions, $70.83 CPA (consider pausing)Keyword Optimization
User: "Show me keywords with quality score below 5 for campaign 12345"
Claude: [Calls google_ads_keyword_performance with filtering]
Found 8 keywords with quality scores below 5:
1. "cheap widgets" - QS: 3, Avg Pos: 4.2, $145 spent
Suggestion: Improve ad relevance or pause
2. "buy widgets online" - QS: 4, Avg Pos: 3.8, $98 spent
Suggestion: Create dedicated ad group with tailored ad copy
...Budget Management
User: "Increase the budget for campaign 67890 to $150 per day"
Claude: [Calls google_ads_update_campaign_budget with budget_amount_micros=150000000]
Budget updated successfully:
- Campaign: Summer Sale 2025
- Old Budget: $100.00/day
- New Budget: $150.00/day
- Effective: ImmediatelySearch Terms Discovery
User: "What search terms are triggering my ads with high impressions but low CTR?"
Claude: [Calls google_ads_search_terms with analysis]
Found 15 search terms with >1000 impressions and CTR <1%:
High Priority:
1. "free widgets" - 5,234 impressions, 0.3% CTR
Recommendation: Add as negative keyword
2. "how to make widgets" - 3,421 impressions, 0.5% CTR
Recommendation: Add as negative keyword (informational intent)Programmatic Usage
If integrating directly with the MCP server programmatically:
from mcp import ClientSession
import asyncio
async def analyze_campaigns():
async with ClientSession() as session:
# Initialize connection
await session.call_tool("google_ads_initialize", {
"developer_token": "YOUR_TOKEN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN"
})
# Get campaign performance
result = await session.call_tool("google_ads_campaign_performance", {
"customer_id": "1234567890",
"date_range": "LAST_7_DAYS",
"response_format": "json"
})
print(result)
asyncio.run(analyze_campaigns())Configuration
Configuration File (config.yaml)
The v2 server supports configuration via YAML files:
authentication:
method: oauth2 # or service_account
developer_token: ${GOOGLE_ADS_DEVELOPER_TOKEN}
client_id: ${GOOGLE_ADS_CLIENT_ID}
client_secret: ${GOOGLE_ADS_CLIENT_SECRET}
refresh_token: ${GOOGLE_ADS_REFRESH_TOKEN}
login_customer_id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID} # Optional MCC
performance:
cache:
backend: memory # Options: memory, redis, none
ttl:
accounts: 3600 # 1 hour
campaigns: 300 # 5 minutes
keywords: 300 # 5 minutes
search_terms: 600 # 10 minutes
redis_url: redis://localhost:6379/0 # If using Redis
max_size: 1000 # For memory cache
connection_pool:
size: 10
timeout: 30
rate_limiting:
enabled: true
requests_per_minute: 60
burst_size: 10
error_handling:
retry:
enabled: true
max_attempts: 3
backoff_strategy: exponential # linear, exponential
initial_delay: 1
max_delay: 30
alerts:
webhook_url: https://your-webhook.com/alerts
email: admin@example.com
log_errors: true
logging:
level: INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
format: json # json, text
file: /var/log/google-mcp/server.log
console: true
features:
batch_operations: true
auto_recommendations: true
advanced_reporting: true
conversion_tracking: true
audience_management: true
api_version: v17 # Google Ads API version
default_page_size: 50
character_limit: 25000 # MCP response size limitEnvironment Variables
Override configuration with environment variables:
# Authentication
export GOOGLE_ADS_DEVELOPER_TOKEN="your-token"
export GOOGLE_ADS_CLIENT_ID="your-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890" # Optional
# Performance
export GOOGLE_MCP_CACHE_BACKEND="redis"
export GOOGLE_MCP_REDIS_URL="redis://localhost:6379/0"
# Logging
export GOOGLE_MCP_LOG_LEVEL="DEBUG"
export GOOGLE_MCP_LOG_FILE="/var/log/google-mcp.log"Feature Flags
Enable or disable features:
features:
batch_operations: true # Bulk operations support
auto_recommendations: true # Google AI recommendations
advanced_reporting: true # 25+ specialized reports
conversion_tracking: true # Conversion management
audience_management: true # Remarketing, Customer MatchCaching Options
Memory Cache (default, no setup required):
Fast, in-process caching
No external dependencies
Limited to single process
Redis Cache (recommended for production):
Distributed caching across processes
Persistent cache across restarts
Supports clustering
No Cache:
Disable caching for testing or debugging
Architecture
Project Structure
google-mcp/
├── google_ads_mcp.py # Main MCP server (v1) - 10 tools
├── google_ads_mcp_v2.py # Enhanced server (v2) - 161 planned tools
├── generate_refresh_token.py # OAuth token generation utility
│
├── Infrastructure Managers
├── auth_manager.py # OAuth authentication & token management
├── config_manager.py # Configuration loading (YAML/JSON)
├── cache_manager.py # Caching layer (Memory/Redis)
├── error_handler.py # Error handling & retry logic
├── logger.py # Structured logging
├── response_handler.py # Response formatting & streaming
├── query_optimizer.py # GAQL query optimization
│
├── Domain Managers
├── campaign_manager.py # Campaign creation & management
├── ad_group_manager.py # Ad group operations
├── ad_manager.py # Ad creation & management
├── keyword_manager.py # Keyword operations
├── bidding_strategy_manager.py # Bidding strategy configuration
├── audience_manager.py # Audience management
├── conversion_manager.py # Conversion tracking
├── automation_manager.py # Automated rules
├── batch_operations_manager.py # Bulk operations
├── extensions_manager.py # Ad extensions
├── labels_manager.py # Label management
├── shopping_pmax_manager.py # Shopping & Performance Max
├── local_app_manager.py # Local & app campaigns
├── insights_manager.py # Analytics & insights
├── reporting_manager.py # Advanced reporting
│
├── MCP Tool Registrations
├── mcp_tools_campaigns.py # Campaign tools
├── mcp_tools_ad_groups.py # Ad group tools
├── mcp_tools_ads.py # Ad tools
├── mcp_tools_keywords.py # Keyword tools
├── mcp_tools_bidding.py # Bidding tools
├── mcp_tools_audiences.py # Audience tools
├── mcp_tools_conversions.py # Conversion tools
├── mcp_tools_automation.py # Automation tools
├── mcp_tools_batch.py # Batch operation tools
├── mcp_tools_extensions.py # Extension tools
├── mcp_tools_shopping_pmax.py # Shopping/PMax tools
├── mcp_tools_local_app.py # Local/App tools
├── mcp_tools_insights.py # Insights tools
├── mcp_tools_reporting.py # Reporting tools
│
├── Configuration
├── config.yaml # Server configuration
├── config.example.yaml # Configuration template
├── requirements.txt # Python dependencies
│
├── Documentation
├── README.md # This file
├── SECURITY.md # Security policy
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # MIT License
├── CITATION.cff # Citation information
├── CODEOWNERS # Code ownership
├── documentation/ # Additional documentation
│ ├── QUICKSTART.md
│ ├── EXECUTIVE_SUMMARY.md
│ ├── EXECUTIVE_SUMMARY.md
│ └── ...
│
└── .claude/ # Claude Code configuration
├── claude_project.json
└── CLAUDE.mdManager Module Pattern
Each domain manager follows this pattern:
class CampaignManager:
"""Handles campaign-related operations."""
def __init__(self, client: GoogleAdsClient, config: Config):
self.client = client
self.config = config
def create_campaign(...) -> dict:
"""Create a new campaign."""
# Validation
# API operation
# Error handling
# Response formattingMCP Tool Registration System
Tools are registered using FastMCP:
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel
mcp = FastMCP("google_ads_mcp")
@mcp.tool()
def google_ads_create_campaign(request: CampaignCreateRequest) -> dict:
"""Create a new Google Ads campaign."""
manager = CampaignManager(client, config)
return manager.create_campaign(**request.dict())Data Flow
AI Assistant sends natural language request
MCP Server receives tool call with parameters
Manager Module validates input and executes API operation
Google Ads API processes the request
Response Handler formats the result (Markdown/JSON)
MCP Server returns the formatted response
AI Assistant presents the result to the user
Troubleshooting
Common Errors
"Client not initialized" Error
Cause: The Google Ads client hasn't been initialized with credentials.
Solution:
Initialize my Google Ads connection with these credentials:
- Developer Token: YOUR_TOKEN
- Client ID: YOUR_CLIENT_ID
- Client Secret: YOUR_SECRET
- Refresh Token: YOUR_REFRESH_TOKEN"Invalid customer ID" Error
Cause: Customer ID format is incorrect.
Solution: Ensure customer IDs are:
10 digits
Without hyphens
Example:
1234567890(correct),123-456-7890(wrong)
"Authentication failed" Error
Causes and solutions:
Developer token invalid:
Verify token in Google Ads API Center
Ensure token is approved (not test-only)
OAuth credentials incorrect:
Regenerate refresh token
Verify Client ID and Client Secret
Token expired:
Refresh tokens can expire after prolonged inactivity
Generate a new refresh token
Wrong login_customer_id:
Only use
login_customer_idfor MCC accountsVerify the MCC ID is correct
"Insufficient permissions" Error
Causes:
Your Google account doesn't have access to the Google Ads account
Developer token has limited access level
OAuth scope doesn't include Google Ads API
Solution:
Verify account access in Google Ads
Ensure OAuth scope is
https://www.googleapis.com/auth/adwordsCheck developer token access level
Rate Limiting
Cause: Exceeded Google Ads API rate limits.
Solutions:
Reduce request frequency
Use smaller date ranges
Enable caching (Memory or Redis)
Implement request throttling
Google Ads API Limits:
15,000 operations per day (test accounts)
Higher limits for production accounts
Contact Google for increased limits
Debug Logging
Enable debug logging for troubleshooting:
v1 (google_ads_mcp.py):
import logging
logging.basicConfig(level=logging.DEBUG)v2 (config.yaml):
logging:
level: DEBUG
console: true
file: /tmp/google-mcp-debug.logTesting Connections
Test your setup manually:
from google.ads.googleads.client import GoogleAdsClient
credentials = {
"developer_token": "YOUR_TOKEN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN",
"use_proto_plus": True
}
client = GoogleAdsClient.load_from_dict(credentials)
customer_service = client.get_service("CustomerService")
accessible_customers = customer_service.list_accessible_customers()
print(f"Accessible customers: {accessible_customers.resource_names}")Getting Help
If you're still stuck:
Check existing issues: GitHub Issues
Review documentation: Google Ads API Docs
Create an issue: Provide error messages, logs, and steps to reproduce
Contact support: See Support & Resources
Advanced Topics
Multi-Account (MCC) Management
What is MCC?
MCC (My Client Center) is a Google Ads manager account that lets you manage multiple client accounts from a single interface.
Setup:
Create an MCC account at ads.google.com/mcc
Link client accounts to your MCC
Use MCC customer ID as
login_customer_idduring initialization
Usage:
Initialize with:
- Login Customer ID: 1234567890 (your MCC ID)
- ...other credentials...
Then access client accounts:
"Analyze campaigns for client account 2345678901"
"List all accounts under my MCC"Benefits:
Single authentication for multiple accounts
Centralized reporting across clients
Efficient bulk operations
Performance Optimization
Caching Strategies:
Memory Cache: Fast, but limited to single process
Redis Cache: Distributed, persistent, recommended for production
Selective Caching: Cache expensive queries, refresh on mutations
Best Practices:
Use date range filters to reduce data volume
Apply
limitparameters to control result sizeEnable caching for frequently accessed data
Use batch operations for bulk changes
Custom GAQL Queries
GAQL (Google Ads Query Language) enables advanced custom queries.
Query Structure:
SELECT
resource.field1,
resource.field2,
metrics.metric1
FROM resource_name
WHERE conditions
ORDER BY field
LIMIT nExample - Find top-performing keywords:
SELECT
ad_group_criterion.keyword.text,
metrics.clicks,
metrics.conversions,
metrics.cost_micros
FROM keyword_view
WHERE
metrics.impressions > 100
AND campaign.status = 'ENABLED'
ORDER BY metrics.conversions DESC
LIMIT 20Resources:
Batch Operations
Efficiently make bulk changes using batch operations (v2 feature):
Benefits:
Reduce API calls (1 batch vs. 100 individual calls)
Faster execution
Lower quota usage
Use Cases:
Bulk keyword uploads
Mass campaign creation
Batch budget updates
Bulk status changes
API Reference
Google Ads API
Documentation: Google Ads API Docs
Reference: API Reference
Field Guide: Field Reference
Release Notes: What's New
GAQL Resources
Query Builder: Interactive Query Builder
Query Validator: Validate Queries
Query Grammar: GAQL Grammar Reference
MCP Protocol
Specification: MCP Specification
Documentation: MCP Docs
GitHub: MCP GitHub
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Ways to contribute:
Report bugs or request features via GitHub Issues
Submit pull requests for bug fixes or new features
Improve documentation
Share usage examples and tips
Development workflow:
Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request
See CONTRIBUTING.md for detailed instructions.
Security
Security is a top priority. Please see SECURITY.md for:
Security policy and supported versions
How to report vulnerabilities
Security best practices
Credential management guidelines
Quick security tips:
Never commit credentials to version control
Use environment variables for secrets
Rotate OAuth tokens regularly
Enable 2FA on Google Ads accounts
Monitor API access logs
License
This project is licensed under the MIT License. See LICENSE for details.
MIT License
Copyright (c) 2025 John O'Connor
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...Citation
If you use this software in your research or project, please cite it:
APA Format:
O'Connor, J. (2025). Google Ads MCP Server (Version 1.0.0) [Computer software].
https://github.com/johnoconnor0/google-ads-mcpBibTeX:
@software{oconnor_google_mcp_2025,
author = {O'Connor, John},
title = {Google Ads MCP Server},
year = {2025},
version = {1.0.0},
url = {https://github.com/johnoconnor0/google-ads-mcp}
}See CITATION.cff for machine-readable citation metadata.
Support & Resources
Documentation
Quick Start: QUICKSTART.md
Implementation Plan: documentation/EXECUTIVE_SUMMARY.md
Executive Summary: EXECUTIVE_SUMMARY.md
Claude Instructions: .claude/CLAUDE.md
Google Ads Resources
Google Ads API: Documentation
Developer Token: Apply Here
OAuth Setup: OAuth Guide
Support: Google Ads API Support
MCP Resources
MCP Documentation: modelcontextprotocol.io
Claude Desktop: Claude Desktop Docs
MCP GitHub: github.com/modelcontextprotocol
Community & Support
GitHub Issues: Report issues or request features
Discussions: GitHub Discussions
Email: open-source@weblifter.com.au
Related Projects
Claude Desktop: AI assistant with MCP support
MCP Servers: Awesome MCP Servers
Google Ads Scripts: Scripts Library
Version: 1.0.0 Last Updated: December 17, 2025 Author: John O'Connor License: MIT
Star this repository if you find it useful!
Available Tools
142 toolsgoogle_ads_account_performanceB
Get account-level performance overview.
Provides high-level metrics for the entire Google Ads account including impressions, clicks, cost, conversions, and impression share.
Args: customer_id: Customer ID (without hyphens) date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Account performance metrics
Example: google_ads_account_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), date_range. Returns: result
google_ads_add_audience_to_ad_groupA
Add audience targeting to an ad group.
Similar to campaign-level audience targeting, but applied at the ad group level for more granular control.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID user_list_id: User list ID to target targeting_mode: OBSERVATION or TARGETING
Returns: Success message
Example: google_ads_add_audience_to_ad_group( customer_id="1234567890", ad_group_id="222222222", user_list_id="12345", targeting_mode="OBSERVATION" )
Inputs: customer_id (required), ad_group_id (required), user_list_id (required), targeting_mode. Returns: result
google_ads_add_audience_to_campaignA
Add audience targeting to a campaign.
Two modes available:
OBSERVATION: Monitor audience performance without restricting reach
TARGETING: Restrict campaign to only show ads to this audience
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID user_list_id: User list ID to target targeting_mode: OBSERVATION (monitor) or TARGETING (restrict reach)
Returns: Success message
Example (Observation): google_ads_add_audience_to_campaign( customer_id="1234567890", campaign_id="111111111", user_list_id="12345", targeting_mode="OBSERVATION" )
Example (Targeting): google_ads_add_audience_to_campaign( customer_id="1234567890", campaign_id="222222222", user_list_id="12345", targeting_mode="TARGETING" )
Recommendation: Start with OBSERVATION mode to gather performance data before switching to TARGETING mode.
Inputs: customer_id (required), campaign_id (required), user_list_id (required), targeting_mode. Returns: result
google_ads_add_call_extensionB
Add call extension to a campaign.
Call extensions display your phone number with a click-to-call button, making it easy for mobile users to contact you directly from the ad.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add call extension phone_number: Phone number in local format (e.g., "(555) 123-4567") country_code: Two-letter country code (default: US) track_calls: Enable call conversion tracking
Returns: Call extension creation result
Example: google_ads_add_call_extension( customer_id="1234567890", campaign_id="12345678", phone_number="(555) 123-4567", country_code="US", track_calls=True )
Inputs: customer_id (required), campaign_id (required), phone_number (required), country_code, +1 more. Returns: result
google_ads_add_callout_extensionA
Add callout extensions to a campaign.
Callouts are short, descriptive snippets that highlight key benefits, features, or offerings. They appear below your ad text.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add callouts callouts_json: JSON array of callout texts
Callout Configuration Schema:
[
{"callout_text": "Free Shipping"},
{"callout_text": "24/7 Support"},
{"callout_text": "Price Match Guarantee"}
]Requirements:
Callout text: 1-25 characters
Minimum 2 callouts recommended
Maximum 10 callouts per campaign
Returns: Callout extension creation result
Example: google_ads_add_callout_extension( customer_id="1234567890", campaign_id="12345678", callouts_json='[{"callout_text": "Free Shipping"}, {"callout_text": "24/7 Support"}]' )
Inputs: customer_id (required), campaign_id (required), callouts_json (required). Returns: result
google_ads_add_campaign_exclusionsA
Add placement and IP exclusions to a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID placement_exclusions: List of URLs/apps to exclude (e.g., ["example.com", "youtube.com/channel/ABC"]) ip_exclusions: List of IP addresses to exclude (e.g., ["192.168.1.1", "10.0.0.0/24"])
Returns: Success message with exclusion summary
Note:
Placement exclusions prevent ads from showing on specific websites, YouTube channels, or apps
IP exclusions prevent ads from showing to specific IP addresses (useful for excluding office IPs)
CIDR notation supported for IP ranges (e.g., "10.0.0.0/24")
Inputs: customer_id (required), campaign_id (required), placement_exclusions, ip_exclusions. Returns: result
google_ads_add_keywordsA
Add keywords to an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keywords: List of keyword dicts with 'text' and 'match_type' (EXACT, PHRASE, BROAD) cpc_bid: Optional default CPC bid for all keywords in currency units
Returns: Success message with keyword count
Example: keywords = [ {"text": "running shoes", "match_type": "PHRASE"}, {"text": "nike shoes", "match_type": "EXACT"}, {"text": "athletic footwear", "match_type": "BROAD"} ]
Inputs: customer_id (required), ad_group_id (required), keywords (required), cpc_bid. Returns: result
google_ads_add_location_extensionA
Add a location extension to display your business address in ads.
Location extensions show your business address, phone number, and a map marker with your ads. They help customers find your physical business locations and increase foot traffic to your stores.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add location extension business_name: Business name (up to 80 characters) address_line_1: Street address city: City name province: State/province code (e.g., "CA", "NY", "TX") postal_code: ZIP or postal code country_code: 2-letter country code (e.g., "US", "GB", "CA") phone_number: Optional phone with country code (e.g., "+1-555-123-4567")
Returns: Location extension creation result
Example: google_ads_add_location_extension( customer_id="1234567890", campaign_id="12345678", business_name="Acme Coffee Shop", address_line_1="123 Main Street", city="San Francisco", province="CA", postal_code="94102", country_code="US", phone_number="+1-415-555-1234" )
Benefits: - Show your address and location on a map - Increase foot traffic to physical locations - Make it easy for customers to find you - Add phone numbers for direct calls - Improve local search visibility
Requirements: - Location extensions require address verification - Best practice: Link with Google My Business - Phone numbers should include country code - All address fields must be valid
Note: For advanced location management, use Google My Business integration with Local campaigns for automatic location syncing and store visit tracking.
Inputs: customer_id (required), campaign_id (required), business_name (required), address_line_1 (required), +5 more. Returns: result
google_ads_add_negative_keywordsA
Add negative keywords to an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keywords: List of keyword dicts with 'text' and 'match_type'
Returns: Success message
Example: keywords = [ {"text": "cheap", "match_type": "BROAD"}, {"text": "free", "match_type": "BROAD"} ]
Inputs: customer_id (required), ad_group_id (required), keywords (required). Returns: result
google_ads_add_price_extensionA
Add price extension to a campaign.
Price extensions display a list of products/services with prices, allowing users to browse your offerings directly in the ad.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add price extension price_qualifier: Qualifier (FROM, UP_TO, AVERAGE, NONE) items_json: JSON array of price items (3-8 items)
Price Item Schema:
[
{
"header": "Basic Plan",
"description": "Perfect for individuals",
"price": 9.99,
"final_url": "https://example.com/basic"
}
]Returns: Price extension creation result
Example: google_ads_add_price_extension( customer_id="1234567890", campaign_id="12345678", price_qualifier="FROM", items_json='[{"header": "Basic", "price": 9.99, "final_url": "https://example.com/basic"}]' )
Inputs: customer_id (required), campaign_id (required), price_qualifier (required), items_json (required). Returns: result
google_ads_add_promotion_extensionA
Add promotion extension to a campaign.
Promotion extensions highlight special offers, sales, and discounts with a prominent visual treatment in your ads.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add promotion promotion_target: What's being promoted (e.g., "Summer Sale") occasion: Occasion (UNKNOWN, NEW_YEARS, VALENTINES_DAY, MOTHERS_DAY, FATHERS_DAY, LABOR_DAY, BACK_TO_SCHOOL, HALLOWEEN, BLACK_FRIDAY, CYBER_MONDAY, CHRISTMAS, BOXING_DAY, INDEPENDENCE_DAY) discount_modifier: Modifier (NONE, UP_TO) money_amount_off: Dollar amount off (e.g., 25.00 for $25 off) percent_off: Percent off (e.g., 20 for 20% off) promotion_code: Optional promo code text
Returns: Promotion extension creation result
Example: google_ads_add_promotion_extension( customer_id="1234567890", campaign_id="12345678", promotion_target="Holiday Sale", occasion="CHRISTMAS", percent_off=25, promotion_code="HOLIDAY25" )
Inputs: customer_id (required), campaign_id (required), promotion_target (required), occasion, +4 more. Returns: result
google_ads_add_sitelink_extensionA
Add sitelink extensions to a campaign.
Sitelinks are additional links that appear below your main ad, directing users to specific pages on your website. They increase ad size, improve CTR, and provide more navigation options.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add sitelinks sitelinks_json: JSON array of sitelink configurations
Sitelink Configuration Schema:
[
{
"link_text": "Shop Now",
"final_url": "https://example.com/shop",
"description1": "Browse our products",
"description2": "Free shipping on orders over $50"
}
]Requirements:
Link text: 1-25 characters
Description1: Optional, 35 characters max
Description2: Optional, 35 characters max
Minimum 2 sitelinks recommended
Returns: Sitelink extension creation result
Example: google_ads_add_sitelink_extension( customer_id="1234567890", campaign_id="12345678", sitelinks_json='[{"link_text": "Shop Now", "final_url": "https://example.com/shop"}]' )
Inputs: customer_id (required), campaign_id (required), sitelinks_json (required). Returns: result
google_ads_add_structured_snippetB
Add structured snippet extension to a campaign.
Structured snippets highlight specific aspects of your products or services in a predefined format (e.g., Types: Economy, Luxury, SUV).
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to add structured snippet header: Snippet header (Types, Brands, Models, Services, Styles, etc.) values_json: JSON array of values (3-10 items)
Common Headers:
Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Services, Shows, Styles, Types
Returns: Structured snippet creation result
Example: google_ads_add_structured_snippet( customer_id="1234567890", campaign_id="12345678", header="Types", values_json='["Economy", "Compact", "Luxury", "SUV"]' )
Inputs: customer_id (required), campaign_id (required), header (required), values_json (required). Returns: result
google_ads_app_conversionsA
Get detailed app conversion data by conversion type.
Retrieves app install and in-app engagement conversions broken down by conversion action and category. Useful for understanding which conversion events are driving campaign performance.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID to filter (returns all if not specified) date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc.
Returns: Dictionary with app conversion data including: - campaigns: Campaign-level conversion breakdown - by_type: Aggregated conversions by category - total_campaigns: Number of campaigns with conversion data
Example:
Get conversion breakdown for all app campaigns:
google_ads_app_conversions( customer_id="1234567890", date_range="LAST_30_DAYS" )
Conversion Categories: - App Installs: First-time app installations - In-App Purchases: Purchases made within the app - In-App Actions: Custom conversion events (level completed, item viewed, etc.) - App Engagement: Session starts, time in app, etc.
Notes: - Requires Firebase or third-party SDK integration for in-app tracking - Install conversions are automatically tracked - In-app conversions require SDK implementation
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_apply_recommendationA
Apply a single optimization recommendation.
This will automatically implement the suggested optimization. For example:
KEYWORD recommendations will add the keyword to your account
CAMPAIGN_BUDGET recommendations will increase the budget
Bidding strategy recommendations will change the bidding strategy
Args: customer_id: Customer ID (without hyphens) recommendation_resource_name: Resource name of the recommendation to apply (obtained from google_ads_get_recommendations)
Returns: Success message confirming application
Example: google_ads_apply_recommendation( customer_id="1234567890", recommendation_resource_name="customers/1234567890/recommendations/12345" )
Warning: This will make changes to your account. Review the recommendation details carefully before applying.
Inputs: customer_id (required), recommendation_resource_name (required). Returns: result
google_ads_apply_recommendations_by_typeA
Apply all recommendations of a specific type.
This is useful for bulk-applying all recommendations of a certain category, such as all KEYWORD recommendations or all CAMPAIGN_BUDGET recommendations.
Args: customer_id: Customer ID (without hyphens) recommendation_type: Type of recommendations to apply (KEYWORD, CAMPAIGN_BUDGET, TARGET_CPA_OPT_IN, etc.) max_to_apply: Optional maximum number of recommendations to apply
Returns: Success message with count of applied recommendations
Example: google_ads_apply_recommendations_by_type( customer_id="1234567890", recommendation_type="KEYWORD", max_to_apply=10 )
Common Types:
KEYWORD: Add suggested keywords
CAMPAIGN_BUDGET: Increase budgets
TARGET_CPA_OPT_IN: Enable Target CPA bidding
TARGET_ROAS_OPT_IN: Enable Target ROAS bidding
RESPONSIVE_SEARCH_AD: Create RSAs
Warning: This will make changes to your account. Review recommendations of this type carefully before bulk applying.
Inputs: customer_id (required), recommendation_type (required), max_to_apply. Returns: result
google_ads_app_performanceA
Get performance metrics for App campaigns.
Retrieves key performance indicators for app campaigns including impressions, clicks, conversions (installs), and cost data.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID to filter (returns all if not specified) date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc.
Returns: Dictionary with app campaign performance data including: - campaigns: List of campaign metrics - total_campaigns: Number of app campaigns
Example:
Get performance for all app campaigns in the last 30 days:
google_ads_app_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Metrics Included: - Impressions: Ad views across all networks - Clicks: User clicks - CTR: Click-through rate - Cost: Total spend - Conversions: App installs or in-app actions - Conversion Value: Value of conversions - Cost per Conversion: Average cost for each conversion
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_assign_bidding_strategyA
Assign a portfolio bidding strategy to a campaign.
This replaces the campaign's current bidding strategy with the specified portfolio strategy, allowing Google's AI to optimize bids across all campaigns using this strategy.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update bidding_strategy_id: Portfolio bidding strategy ID to assign
Returns: Success message confirming assignment
Example: google_ads_assign_bidding_strategy( customer_id="1234567890", campaign_id="111111111", bidding_strategy_id="12345" )
Inputs: customer_id (required), campaign_id (required), bidding_strategy_id (required). Returns: result
google_ads_auction_insightsA
Get auction insights and competitive intelligence for a campaign.
Provides:
Impression share metrics (overall, top, absolute top)
Competitive position analysis
Primary constraints (budget vs. ad rank)
Specific recommendations to improve auction performance
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to analyze date_range: Date range (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS)
Returns: Auction insights with competitive analysis
Example: google_ads_auction_insights( customer_id="1234567890", campaign_id="12345678", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id (required), date_range. Returns: result
google_ads_auto_apply_safe_recommendationsA
Auto-apply low-risk, high-impact recommendations.
This tool identifies "safe" recommendations that are unlikely to negatively impact performance and applies them automatically. Safe recommendations include:
Keyword match type upgrades (exact → phrase → broad)
Responsive search ad suggestions
Search partners opt-in
Optimize ad rotation
Higher risk recommendations (budget increases, bidding strategy changes) are excluded and should be reviewed manually.
Args: customer_id: Customer ID (without hyphens) dry_run: If True, shows what would be applied without actually applying (default: True)
Returns: List of recommendations that were (or would be) applied
Example: # Preview what would be applied google_ads_auto_apply_safe_recommendations( customer_id="1234567890", dry_run=True )
# Actually apply the recommendations
google_ads_auto_apply_safe_recommendations(
customer_id="1234567890",
dry_run=False
)Warning: Even "safe" recommendations can impact performance. Use dry_run=True first to review what would be applied.
Inputs: customer_id (required), dry_run. Returns: result
google_ads_batch_add_keywordsA
Add multiple keywords in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) keywords_json: JSON array of keyword configurations
Keyword Configuration Schema:
[
{
"ad_group_id": "12345678",
"text": "keyword phrase",
"match_type": "EXACT",
"cpc_bid": 1.50
}
]Required Fields: ad_group_id, text Optional Fields: match_type (default: BROAD), cpc_bid Match Types: EXACT, PHRASE, BROAD
Returns: Batch operation result with success/failure details
Example: google_ads_batch_add_keywords( customer_id="1234567890", keywords_json='[{"ad_group_id": "12345678", "text": "running shoes", "match_type": "EXACT"}]' )
Inputs: customer_id (required), keywords_json (required). Returns: result
google_ads_batch_create_ad_groupsA
Create multiple ad groups in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) ad_groups_json: JSON array of ad group configurations
Ad Group Configuration Schema:
[
{
"name": "Ad Group Name",
"campaign_id": "12345678",
"status": "PAUSED",
"cpc_bid": 2.50
}
]Required Fields: name, campaign_id Optional Fields: status (default: PAUSED), cpc_bid
Returns: Batch operation result with success/failure details
Example: google_ads_batch_create_ad_groups( customer_id="1234567890", ad_groups_json='[{"name": "Ad Group 1", "campaign_id": "12345678", "cpc_bid": 2.50}]' )
Inputs: customer_id (required), ad_groups_json (required). Returns: result
google_ads_batch_create_adsA
Create multiple responsive search ads in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) ads_json: JSON array of ad configurations
Ad Configuration Schema:
[
{
"ad_group_id": "12345678",
"headlines": ["Headline 1", "Headline 2", "Headline 3"],
"descriptions": ["Description 1", "Description 2"],
"final_urls": ["https://example.com"]
}
]Required Fields: ad_group_id, headlines (3-15), descriptions (2-4), final_urls
Returns: Batch operation result with success/failure details
Example: google_ads_batch_create_ads( customer_id="1234567890", ads_json='[{"ad_group_id": "12345678", "headlines": ["H1", "H2", "H3"], ...}]' )
Inputs: customer_id (required), ads_json (required). Returns: result
google_ads_batch_create_campaignsA
Create multiple campaigns in a single batch operation.
Supports partial failure - some campaigns may succeed while others fail.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaigns_json: JSON array of campaign configurations
Campaign Configuration Schema:
[
{
"name": "Campaign Name",
"type": "SEARCH",
"status": "PAUSED",
"budget_amount": 50.00,
"bidding_strategy": "MAXIMIZE_CONVERSIONS",
"target_cpa": 25.00
}
]Required Fields: name, budget_amount Optional Fields: type (default: SEARCH), status (default: PAUSED), bidding_strategy, target_cpa
Returns: Batch operation result with success/failure details
Example: google_ads_batch_create_campaigns( customer_id="1234567890", campaigns_json='[{"name": "Campaign 1", "budget_amount": 50}, ...]' )
Inputs: customer_id (required), campaigns_json (required). Returns: result
google_ads_batch_enable_campaignsA
Enable multiple campaigns in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_ids: Comma-separated list of campaign IDs
Returns: Batch operation result
Example: google_ads_batch_enable_campaigns( customer_id="1234567890", campaign_ids="12345678,87654321,11111111" )
Inputs: customer_id (required), campaign_ids (required). Returns: result
google_ads_batch_pause_campaignsB
Pause multiple campaigns in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_ids: Comma-separated list of campaign IDs
Returns: Batch operation result
Example: google_ads_batch_pause_campaigns( customer_id="1234567890", campaign_ids="12345678,87654321,11111111" )
Inputs: customer_id (required), campaign_ids (required). Returns: result
google_ads_batch_set_ad_group_url_suffixesA
Bulk set Final URL suffixes for multiple ad groups in one API call.
Args: customer_id: Customer ID (without hyphens) ad_group_suffixes: JSON string containing array of objects with 'ad_group_id' and 'url_suffix'. Example: [{"ad_group_id": "123", "url_suffix": "sm_kw=bollards"}, {"ad_group_id": "456", "url_suffix": "sm_kw=wheel-stops"}]
Returns: Success message with count of updated ad groups
Inputs: customer_id (required), ad_group_suffixes (required). Returns: result
google_ads_batch_status_changeA
Change status for multiple entities (campaigns, ad groups, keywords, ads).
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) entity_type: Type of entity (campaign, ad_group, keyword, ad) status_updates_json: JSON array of status update configurations
Status Update Schema (Campaign/Ad Group):
[
{
"entity_id": "12345678",
"status": "ENABLED"
}
]Status Update Schema (Keyword/Ad):
[
{
"ad_group_id": "12345678",
"entity_id": "87654321",
"status": "ENABLED"
}
]Valid Statuses:
Campaign: ENABLED, PAUSED, REMOVED
Ad Group: ENABLED, PAUSED, REMOVED
Keyword: ENABLED, PAUSED, REMOVED
Ad: ENABLED, PAUSED, REMOVED
Returns: Batch operation result
Example: google_ads_batch_status_change( customer_id="1234567890", entity_type="campaign", status_updates_json='[{"entity_id": "12345678", "status": "ENABLED"}]' )
Inputs: customer_id (required), entity_type (required), status_updates_json (required). Returns: result
google_ads_batch_update_bidsA
Update CPC bids for multiple keywords or ad groups in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) entity_type: Type of entity (keyword or ad_group) bid_updates_json: JSON array of bid update configurations
Bid Update Schema (Keywords):
[
{
"ad_group_id": "12345678",
"criterion_id": "87654321",
"cpc_bid": 2.50
}
]Bid Update Schema (Ad Groups):
[
{
"ad_group_id": "12345678",
"cpc_bid": 2.50
}
]Returns: Batch operation result with success/failure details
Example: google_ads_batch_update_bids( customer_id="1234567890", entity_type="keyword", bid_updates_json='[{"ad_group_id": "12345678", "criterion_id": "87654321", "cpc_bid": 2.50}]' )
Inputs: customer_id (required), entity_type (required), bid_updates_json (required). Returns: result
google_ads_batch_update_budgetsA
Update budgets for multiple campaigns in a single batch operation.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) budget_updates_json: JSON array of budget update configurations
Budget Update Schema:
[
{
"campaign_id": "12345678",
"budget_amount": 75.00
}
]Required Fields: campaign_id, budget_amount (daily budget in currency units)
Returns: Batch operation result with success/failure details
Example: google_ads_batch_update_budgets( customer_id="1234567890", budget_updates_json='[{"campaign_id": "12345678", "budget_amount": 75.00}]' )
Inputs: customer_id (required), budget_updates_json (required). Returns: result
google_ads_budget_pacingA
Analyze budget pacing and spending velocity for a campaign.
Shows:
Current spend vs. expected spend
Pacing percentage (overpacing, underpacing, on track)
Projected month-end spend
Days remaining in the month
Recommendations for budget adjustments
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to analyze
Returns: Budget pacing analysis with recommendations
Example: google_ads_budget_pacing( customer_id="1234567890", campaign_id="12345678" )
Inputs: customer_id (required), campaign_id (required). Returns: result
google_ads_budget_recommendationsA
Generate AI-powered budget reallocation recommendations.
Identifies:
Budget-constrained campaigns losing impression share
Underperforming campaigns with excessive spend
High ROAS campaigns deserving more budget
Prioritized recommendations with expected impact
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) date_range: Date range for analysis (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS)
Returns: Budget reallocation recommendations prioritized by impact
Example: google_ads_budget_recommendations( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), date_range. Returns: result
google_ads_bulk_add_keywordsC
Bulk add multiple keywords with the same match type.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keyword_texts: List of keyword text strings match_type: Match type for all keywords (EXACT, PHRASE, or BROAD, default: PHRASE) cpc_bid: Optional CPC bid for all keywords in currency units
Returns: Success message
Example: keyword_texts = ["running shoes", "athletic shoes", "sport shoes"]
Inputs: customer_id (required), ad_group_id (required), keyword_texts (required), match_type, +1 more. Returns: result
google_ads_bulk_apply_recommendationsA
Apply multiple recommendations at once.
This is useful for applying several recommendations efficiently in a single operation.
Args: customer_id: Customer ID (without hyphens) recommendation_resource_names: List of recommendation resource names to apply
Returns: Success message with count of applied recommendations
Example: google_ads_bulk_apply_recommendations( customer_id="1234567890", recommendation_resource_names=[ "customers/1234567890/recommendations/12345", "customers/1234567890/recommendations/12346", "customers/1234567890/recommendations/12347" ] )
Warning: This will make changes to your account. Review all recommendations carefully before applying in bulk.
Inputs: customer_id (required), recommendation_resource_names (required). Returns: result
google_ads_bulk_dismiss_recommendationsA
Dismiss multiple recommendations at once.
Args: customer_id: Customer ID (without hyphens) recommendation_resource_names: List of recommendation resource names to dismiss
Returns: Success message with count of dismissed recommendations
Example: google_ads_bulk_dismiss_recommendations( customer_id="1234567890", recommendation_resource_names=[ "customers/1234567890/recommendations/12345", "customers/1234567890/recommendations/12346" ] )
Inputs: customer_id (required), recommendation_resource_names (required). Returns: result
google_ads_bulk_update_ad_group_statusA
Update status for multiple ad groups at once.
Args: customer_id: Customer ID (without hyphens) ad_group_ids: List of ad group IDs to update status: New status for all ad groups (ENABLED, PAUSED, or REMOVED)
Returns: Success message with count of updated ad groups
Example: ad_group_ids = ["123456789", "987654321", "456789123"]
Inputs: customer_id (required), ad_group_ids (required), status (required). Returns: result
google_ads_bulk_update_ad_statusA
Update status for multiple ads at once.
Args: customer_id: Customer ID (without hyphens) status_updates: List of dicts with 'ad_group_id' and 'ad_id' status: New status for all ads (ENABLED, PAUSED, or REMOVED)
Returns: Success message
Example: status_updates = [ {"ad_group_id": "123", "ad_id": "456"}, {"ad_group_id": "123", "ad_id": "789"} ]
Inputs: customer_id (required), status_updates (required), status (required). Returns: result
google_ads_bulk_update_keyword_bidsA
Update bids for multiple keywords at once.
Args: customer_id: Customer ID (without hyphens) bid_updates: List of dicts with 'ad_group_id', 'criterion_id', 'cpc_bid'
Returns: Success message
Example: bid_updates = [ {"ad_group_id": "123", "criterion_id": "456", "cpc_bid": 2.50}, {"ad_group_id": "123", "criterion_id": "789", "cpc_bid": 3.00} ]
Inputs: customer_id (required), bid_updates (required). Returns: result
google_ads_campaign_comparisonA
Compare performance across multiple campaigns side-by-side.
Analyze and compare metrics across 2-10 campaigns to identify best performers, optimize budget allocation, and find underperforming campaigns.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_ids: Comma-separated campaign IDs (e.g., "123,456,789") date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc. response_format: Output format (markdown or json)
Returns: Comparative analysis with rankings and insights
Example: google_ads_campaign_comparison( customer_id="1234567890", campaign_ids="111111,222222,333333", date_range="LAST_30_DAYS" )
Comparison Metrics: - Impressions, clicks, CTR - Cost and average CPC - Conversions and cost per conversion - Conversion value and ROAS - Share of total (% of overall performance)
Use Cases: - Identify top performers for budget increases - Find underperformers to optimize or pause - Compare A/B test campaigns - Analyze campaign strategy effectiveness - Guide budget reallocation decisions
Inputs: customer_id (required), campaign_ids (required), date_range, response_format. Returns: result
google_ads_campaign_performanceA
Get comprehensive performance metrics for campaigns.
Retrieves key performance indicators including cost, clicks, impressions, CTR, conversions, and more for campaigns in the specified date range. Supports filtering by status and cost thresholds.
Args: customer_id: Customer ID without hyphens (e.g., '1234567890') date_range: Predefined date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_90_DAYS) campaign_status: Filter by status list e.g. ['ENABLED', 'PAUSED'] min_cost: Minimum cost filter in currency units limit: Maximum number of campaigns to return (1-100) response_format: Output format: 'markdown' or 'json'
Returns: Campaign performance data with metrics and analysis
Inputs: customer_id (required), date_range, campaign_status, min_cost, +2 more. Returns: result
google_ads_check_ad_approval_statusB
Check ad approval and policy status.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID
Returns: Approval status details
Inputs: customer_id (required), ad_group_id (required), ad_id (required). Returns: result
google_ads_compare_ad_performanceC
Compare performance between two ads (A/B testing).
Args: customer_id: Customer ID (without hyphens) ad_id_1: First ad ID ad_id_2: Second ad ID date_range: Date range for comparison
Returns: Comparison report
Inputs: customer_id (required), ad_id_1 (required), ad_id_2 (required), date_range. Returns: result
google_ads_compare_periodsC
Compare performance between two time periods.
Args: customer_id: Customer ID (without hyphens) current_start: Current period start (YYYY-MM-DD) current_end: Current period end (YYYY-MM-DD) previous_start: Previous period start (YYYY-MM-DD) previous_end: Previous period end (YYYY-MM-DD)
Returns: Period-over-period comparison with changes
Example: google_ads_compare_periods( customer_id="1234567890", current_start="2025-12-01", current_end="2025-12-15", previous_start="2025-11-01", previous_end="2025-11-15" )
Inputs: customer_id (required), current_start (required), current_end (required), previous_start (required), +1 more. Returns: result
google_ads_conversion_summary_reportC
Get account-wide conversion summary.
Args: customer_id: Customer ID (without hyphens) date_range: Date range
Returns: Summary of all conversions
Example: google_ads_conversion_summary_report( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), date_range. Returns: result
google_ads_create_ad_groupA
Create a new ad group within a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to create ad group in ad_group_name: Name for the ad group cpc_bid: Cost-per-click bid in currency units (e.g., 1.50 for $1.50) status: Initial status (ENABLED or PAUSED, default: PAUSED) ad_group_type: Optional ad group type (SEARCH_STANDARD, DISPLAY_STANDARD, etc.)
Returns: Success message with ad group details
Note: Ad groups are created PAUSED by default for safety.
Inputs: customer_id (required), campaign_id (required), ad_group_name (required), cpc_bid, +2 more. Returns: result
google_ads_create_app_campaignA
Create a Universal App Campaign (UAC) to promote mobile app installs and engagement.
App campaigns automatically optimize ad creative and placement across Google Search, Display Network, YouTube, and Google Play to drive app installs and in-app actions.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_name: Name for the app campaign app_id: App store identifier (bundle ID for iOS, package name for Android) app_store: "APPLE_APP_STORE" or "GOOGLE_APP_STORE" budget_amount: Daily budget in account currency bidding_strategy_goal_type: Bidding goal - one of: - OPTIMIZE_INSTALLS_TARGET_INSTALL_COST (target CPA for installs) - OPTIMIZE_IN_APP_CONVERSIONS_TARGET_INSTALL_COST (target CPA for installs + conversions) - OPTIMIZE_IN_APP_CONVERSIONS_TARGET_CONVERSION_COST (target CPA for conversions) - OPTIMIZE_RETURN_ON_ADVERTISING_SPEND (target ROAS) - OPTIMIZE_PRE_REGISTRATION_CONVERSION_VOLUME (pre-registration campaigns) target_cpa: Optional target cost per action (for CPA-based strategies)
Returns: Dictionary with campaign creation results including: - campaign_id: Created campaign ID - campaign_name: Campaign name - resource_name: Full resource name - app_id: App store identifier - app_store: App store type - budget: Daily budget amount - bidding_goal: Selected bidding strategy goal
Example:
Create an iOS app campaign optimizing for installs:
google_ads_create_app_campaign( customer_id="1234567890", campaign_name="iOS App Install Campaign", app_id="com.example.myapp", app_store="APPLE_APP_STORE", budget_amount=100.0, bidding_strategy_goal_type="OPTIMIZE_INSTALLS_TARGET_INSTALL_COST", target_cpa=5.0 )
Notes: - Campaigns start in PAUSED status - Requires app store listing to be live - Automatic ad creation from app store assets - Can add text, image, video, and HTML5 assets for better performance
Inputs: customer_id (required), campaign_name (required), app_id (required), app_store (required), +3 more. Returns: result
google_ads_create_asset_groupA
Create an asset group for a Performance Max campaign.
Asset groups contain the creative assets (images, videos, text) that Performance Max uses across different Google channels.
PMax requires text assets AND image assets at creation time. Provide headlines, descriptions, long headline, and link existing image assets.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Performance Max campaign ID asset_group_name: Name for this asset group final_urls: Comma-separated list of landing page URLs headlines: List of headlines (3-15, max 30 chars each) descriptions: List of descriptions (2-5, max 90 chars each) long_headline: Single long headline (max 90 characters) existing_assets: List of existing assets to link, each with 'resource_name' and 'field_type' (e.g. MARKETING_IMAGE)
Returns: Asset group creation result
Example: google_ads_create_asset_group( customer_id="1234567890", campaign_id="12345678", asset_group_name="Main Products", final_urls="https://example.com/products", headlines=["Buy Now", "Shop Today", "Free Shipping"], descriptions=["Shop the latest products", "Quality guaranteed"], long_headline="Shop Our Complete Product Line Today" )
Inputs: customer_id (required), campaign_id (required), asset_group_name (required), final_urls (required), +4 more. Returns: result
google_ads_create_bidding_strategyA
Create a portfolio bidding strategy for shared use across campaigns.
Portfolio bidding strategies allow you to apply the same automated bidding strategy across multiple campaigns, enabling Google's AI to optimize bids based on a larger pool of data.
Strategy Types:
TARGET_CPA: Optimize for target cost per acquisition
TARGET_ROAS: Optimize for target return on ad spend
MAXIMIZE_CONVERSIONS: Get the most conversions within budget
MAXIMIZE_CONVERSION_VALUE: Maximize total conversion value
TARGET_IMPRESSION_SHARE: Target specific impression share percentage
MANUAL_CPC: Manual bidding with optional enhanced CPC
Args: customer_id: Customer ID (without hyphens) strategy_name: Name for the bidding strategy (e.g., "High Value Customers") strategy_type: Strategy type (TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, etc.) target_cpa: Target cost per acquisition in currency units (required for TARGET_CPA) target_roas: Target return on ad spend as decimal (e.g., 4.0 = 400% ROAS) (for TARGET_ROAS) target_impression_share: Target impression share 0.0-1.0 (e.g., 0.75 = 75%) (for TARGET_IMPRESSION_SHARE) impression_share_location: Where to target impressions (ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE) max_cpc_bid: Maximum CPC bid limit in currency units (optional for TARGET_IMPRESSION_SHARE) enhanced_cpc: Enable enhanced CPC for MANUAL_CPC strategy
Returns: Success message with strategy ID and configuration details
Example: google_ads_create_bidding_strategy( customer_id="1234567890", strategy_name="Target CPA - $25", strategy_type="TARGET_CPA", target_cpa=25.00 )
Inputs: customer_id (required), strategy_name (required), strategy_type (required), target_cpa, +5 more. Returns: result
google_ads_create_campaignB
Create a new Google Ads campaign.
Args: customer_id: Customer ID (without hyphens) campaign_name: Name for the campaign campaign_type: Type of campaign (SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX, APP, LOCAL) daily_budget: Daily budget in currency units (e.g., 50.00 for $50/day) bidding_strategy: Bidding strategy (MANUAL_CPC, MAXIMIZE_CONVERSIONS, TARGET_CPA, TARGET_ROAS, etc.) status: Initial status (ENABLED or PAUSED, default: PAUSED for safety) enable_search_network: Target Google search network (default: True) enable_search_partners: Target search partner sites (default: False) enable_display_network: Target display network (default: False) start_date: Campaign start date in YYYY-MM-DD format (optional) end_date: Campaign end date in YYYY-MM-DD format (optional) target_cpa: Target CPA in currency units (required for TARGET_CPA strategy) target_roas: Target ROAS as decimal (required for TARGET_ROAS strategy)
Returns: Success message with campaign details
Inputs: customer_id (required), campaign_name (required), campaign_type (required), daily_budget (required), +9 more. Returns: result
google_ads_create_conversion_actionA
Create a conversion action for tracking.
Args: customer_id: Customer ID (without hyphens) conversion_name: Name for the conversion (e.g., "Purchase", "Lead Form") category: Conversion category (PURCHASE, SIGNUP, LEAD, etc.) origin: Where conversions occur (WEBSITE, APP, CALL_FROM_ADS, IMPORT) value: Optional default conversion value always_use_default_value: If True, always use default value (ignore transaction-specific values) count_type: ONE (count once per click) or MANY (count every conversion) click_lookback_days: Attribution window for clicks (1-90 days) view_lookback_days: Attribution window for views (1-30 days)
Returns: Success message with conversion action ID and tag snippet
Example: google_ads_create_conversion_action( customer_id="1234567890", conversion_name="Purchase", category="PURCHASE", origin="WEBSITE", value=50.00, count_type="ONE" )
Categories: PURCHASE, SIGNUP, LEAD, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, PHONE_CALL_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, etc.
Inputs: customer_id (required), conversion_name (required), category (required), origin (required), +5 more. Returns: result
google_ads_create_local_campaignA
Create a Local campaign to drive store visits and foot traffic.
Local campaigns promote physical business locations through Google properties including Search, Maps, Display, and YouTube. They require Google My Business integration and optimize for local actions (store visits, calls, directions).
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_name: Name for the local campaign budget_amount: Daily budget in account currency location_ids: List of Google My Business location IDs optimization_goal: Optimization goal - "STORE_VISITS" or "STORE_SALES"
Returns: Dictionary with campaign creation results including: - campaign_id: Created campaign ID - campaign_name: Campaign name - resource_name: Full resource name - budget: Daily budget amount - location_count: Number of locations - optimization_goal: Selected optimization goal
Example:
Create a local campaign for 3 store locations:
google_ads_create_local_campaign( customer_id="1234567890", campaign_name="Summer Store Promotions", budget_amount=50.0, location_ids=["loc_123", "loc_456", "loc_789"], optimization_goal="STORE_VISITS" )
Notes: - Requires Google My Business account linking - Campaigns start in PAUSED status - Store visit data may take 4-6 weeks to accumulate - Automatically optimizes ad placement across Google properties
Inputs: customer_id (required), campaign_name (required), budget_amount (required), location_ids (required), +1 more. Returns: result
google_ads_create_performance_max_campaignA
Create a Performance Max campaign.
Performance Max uses Google's AI to optimize across all Google channels: Search, Display, YouTube, Gmail, Discover, and Maps.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_name: Name for the Performance Max campaign budget_amount: Daily budget in currency units conversion_goals_json: JSON array of conversion action names target_roas: Optional target return on ad spend (e.g., 3.0 for 300%) target_cpa: Optional target cost per acquisition (if not using ROAS)
Example: google_ads_create_performance_max_campaign( customer_id="1234567890", campaign_name="PMax - All Products", budget_amount=150.00, conversion_goals_json='["Purchase", "Add to Cart"]', target_roas=4.0 )
Inputs: customer_id (required), campaign_name (required), budget_amount (required), conversion_goals_json (required), +2 more. Returns: result
google_ads_create_product_groupA
Create a product group (product partition) in a shopping ad group.
Product groups organize your products and allow different bids for different product segments. You can partition by: brand, category, condition, type, etc.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) ad_group_id: Shopping ad group ID product_condition: Filter by condition (NEW, USED, REFURBISHED) product_type: Filter by product type from your feed is_subdivision: True to create subdivision (for further partitioning), False to create bidding unit
Returns: Product group creation result
Example: google_ads_create_product_group( customer_id="1234567890", ad_group_id="12345678", product_condition="NEW", is_subdivision=False )
Inputs: customer_id (required), ad_group_id (required), product_condition, product_type, +1 more. Returns: result
google_ads_create_responsive_search_adA
Create a Responsive Search Ad (RSA).
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID headlines: List of 3-15 headline texts (max 30 chars each) descriptions: List of 2-4 description texts (max 90 chars each) final_urls: List of final URLs (landing pages) path1: Optional display path 1 (max 15 chars) path2: Optional display path 2 (max 15 chars) status: Initial status (ENABLED or PAUSED, default: PAUSED)
Returns: Success message with ad details
Example: headlines = [ "Premium Running Shoes", "Free Shipping Today", "Shop Nike & Adidas" ] descriptions = [ "Browse our selection of top running shoes", "30-day money back guarantee" ] final_urls = ["https://example.com/shoes"]
Inputs: customer_id (required), ad_group_id (required), headlines (required), descriptions (required), +4 more. Returns: result
google_ads_create_shopping_campaignA
Create a Google Shopping campaign.
Shopping campaigns promote products from your Google Merchant Center account. They show product ads with images, prices, and store names on Google Search and Google Shopping.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_name: Name for the shopping campaign merchant_center_id: Your Merchant Center account ID budget_amount: Daily budget in currency units (e.g., 50.00 for $50/day) priority: Campaign priority (LOW, MEDIUM, HIGH) - affects bidding when multiple campaigns target the same product target_roas: Optional target return on ad spend (e.g., 3.0 for 300% ROAS) enable_local: Enable local inventory ads (requires local product feed)
Returns: Shopping campaign creation result
Example: google_ads_create_shopping_campaign( customer_id="1234567890", campaign_name="Holiday Shopping Campaign", merchant_center_id="123456789", budget_amount=100.00, priority="HIGH", target_roas=3.5 )
Inputs: customer_id (required), campaign_name (required), merchant_center_id (required), budget_amount (required), +3 more. Returns: result
google_ads_create_user_listA
Create a remarketing user list (audience).
User lists allow you to target specific groups of users based on their interactions with your business. Types include:
CRMBASED: Customer Match lists (email, phone, address)
RULE_BASED: Website visitors matching URL patterns
Args: customer_id: Customer ID (without hyphens) list_name: Name for the user list (e.g., "Newsletter Subscribers") description: Optional description membership_days: How long users stay in the list (1-540 days, default: 540) list_type: Type of list (CRMBASED or RULE_BASED) url_contains: For RULE_BASED lists, URL patterns to match (OR logic). e.g. ["arcadium.com.au"] or ["/escape-rooms", "/pricing"]
Returns: Success message with user list ID
Example: google_ads_create_user_list( customer_id="1234567890", list_name="All Site Visitors", description="All visitors to our website", membership_days=90, list_type="RULE_BASED", url_contains=["example.com"] )
Note: RULE_BASED lists require remarketing tags on your website/app.
Inputs: customer_id (required), list_name (required), description, membership_days, +2 more. Returns: result
google_ads_custom_queryA
Execute a custom Google Ads Query Language (GAQL) query.
For advanced users who want to write their own GAQL queries. Use the Google Ads Query Builder to construct queries: https://developers.google.com/google-ads/api/fields/latest/overview_query_builder
Args: customer_id: Customer ID (without hyphens) query: GAQL query string response_format: Output format ('json' or 'markdown')
Returns: Query results in specified format
Inputs: customer_id (required), query (required), response_format. Returns: result
google_ads_device_performanceB
Get performance by device type (mobile, desktop, tablet).
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range
Returns: Performance breakdown by device
Example: google_ads_device_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_dismiss_recommendationA
Dismiss a recommendation without applying it.
Use this when you don't want to apply a recommendation and want to remove it from your recommendations list.
Args: customer_id: Customer ID (without hyphens) recommendation_resource_name: Resource name of the recommendation to dismiss
Returns: Success message confirming dismissal
Example: google_ads_dismiss_recommendation( customer_id="1234567890", recommendation_resource_name="customers/1234567890/recommendations/12345" )
Inputs: customer_id (required), recommendation_resource_name (required). Returns: result
google_ads_duplicate_campaignA
Duplicate an existing campaign with all settings.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to duplicate new_name: Name for the new campaign include_ad_groups: Whether to copy ad groups and their content (default: False)
Returns: Success message with new campaign details
Note: The new campaign will be created in PAUSED status for safety.
Inputs: customer_id (required), campaign_id (required), new_name (required), include_ad_groups. Returns: result
google_ads_estimate_keyword_trafficB
Get traffic estimates for keywords.
Args: customer_id: Customer ID (without hyphens) keywords: List of keyword texts to estimate location_ids: Optional location IDs for targeting (e.g., ["2840"] for United States)
Returns: Traffic estimates
Note: This is a placeholder. Full implementation requires Keyword Plan API setup.
Inputs: customer_id (required), keywords (required), location_ids. Returns: result
google_ads_export_to_csvA
Export account structure to CSV format.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) entity_type: Type to export (campaigns, keywords) campaign_id: Optional campaign ID filter (for keywords export)
Returns: CSV formatted data
Example: google_ads_export_to_csv( customer_id="1234567890", entity_type="campaigns" )
Inputs: customer_id (required), entity_type (required), campaign_id. Returns: result
google_ads_extension_performance_reportA
Get performance metrics for ad extensions.
Shows which extensions are performing well and driving clicks, helping you optimize your extension strategy.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID filter date_range: Date range (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS)
Returns: Extension performance report
Example: google_ads_extension_performance_report( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_geographic_performanceB
Get performance by geographic location.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range
Returns: Performance breakdown by location
Example: google_ads_geographic_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_get_ad_detailsC
Get detailed information about an ad.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID
Returns: Detailed ad information
Inputs: customer_id (required), ad_group_id (required), ad_id (required). Returns: result
google_ads_get_ad_group_detailsC
Get detailed information about an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID
Returns: Detailed ad group information
Inputs: customer_id (required), ad_group_id (required). Returns: result
google_ads_get_ad_group_performanceB
Get performance metrics for an ad group over a date range.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Performance metrics
Inputs: customer_id (required), ad_group_id (required), date_range. Returns: result
google_ads_get_ad_performanceB
Get ad performance metrics.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Optional ad group ID to filter date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Ad performance report
Inputs: customer_id (required), ad_group_id, date_range. Returns: result
google_ads_get_audience_performanceA
Get performance metrics by audience.
See which audiences are driving the best results in terms of clicks, conversions, and ROI.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter date_range: Date range (TODAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Performance breakdown by audience
Example: google_ads_get_audience_performance( customer_id="1234567890", campaign_id="111111111", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_get_bidding_strategy_detailsA
Get full configuration details for a portfolio bidding strategy.
Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID
Returns: Complete strategy configuration and settings
Example: google_ads_get_bidding_strategy_details( customer_id="1234567890", bidding_strategy_id="12345" )
Inputs: customer_id (required), bidding_strategy_id (required). Returns: result
google_ads_get_bidding_strategy_performanceA
Get performance metrics for a portfolio bidding strategy.
Shows aggregate performance across all campaigns using this strategy, including impressions, clicks, conversions, and cost metrics.
Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Performance metrics in markdown format
Example: google_ads_get_bidding_strategy_performance( customer_id="1234567890", bidding_strategy_id="12345", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), bidding_strategy_id (required), date_range. Returns: result
google_ads_get_bid_recommendationsA
Get AI-powered bid recommendations from Google Ads.
Google's recommendation engine analyzes your account performance and suggests specific bid changes to improve results. Recommendations may include:
Keyword bid adjustments
Campaign budget increases
Bidding strategy changes
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter recommendations
Returns: List of bid recommendations with projected impact
Example: google_ads_get_bid_recommendations( customer_id="1234567890", campaign_id="111111111" )
Inputs: customer_id (required), campaign_id. Returns: result
google_ads_get_bid_simulatorA
Get bid simulation data showing potential performance at different bid levels.
Bid simulators use historical data to project how different bid amounts would have affected impressions, clicks, cost, and conversions. This helps you find the optimal bid level for your goals.
Note: Simulations require at least 7 days of historical data.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID for campaign-level simulation criterion_id: Optional keyword criterion ID for keyword-level simulation
Returns: Bid simulation data with projected performance at different bid levels
Example: google_ads_get_bid_simulator( customer_id="1234567890", campaign_id="111111111" )
Inputs: customer_id (required), campaign_id (required), criterion_id. Returns: result
google_ads_get_campaign_detailsC
Get detailed information about a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID
Returns: Detailed campaign information
Inputs: customer_id (required), campaign_id (required). Returns: result
google_ads_get_conversion_performanceC
Get conversion performance metrics.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Optional specific conversion date_range: Date range
Returns: Conversion performance data
Example: google_ads_get_conversion_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), conversion_action_id, date_range. Returns: result
google_ads_get_conversion_tagA
Get the tracking tag/snippet for a website conversion action.
Returns the Global Site Tag and Event Snippet that must be installed on your website to track conversions.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID
Returns: Tracking tag code snippets
Example: google_ads_get_conversion_tag( customer_id="1234567890", conversion_action_id="12345" )
Inputs: customer_id (required), conversion_action_id (required). Returns: result
google_ads_get_customer_match_statusA
Get Customer Match upload status, match rate, and list size.
Check this 24-48 hours after uploading to see how many records matched and if the list is large enough for targeting (minimum 1,000).
Args: customer_id: Customer ID (without hyphens) user_list_id: User list ID to check
Returns: Upload status, match rate, and list sizes
Example: google_ads_get_customer_match_status( customer_id="1234567890", user_list_id="12345" )
Inputs: customer_id (required), user_list_id (required). Returns: result
google_ads_get_keyword_performanceC
Get keyword performance metrics.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Optional ad group ID to filter by date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Keyword performance report
Inputs: customer_id (required), ad_group_id, date_range. Returns: result
google_ads_get_keyword_quality_scoreB
Get detailed quality score information for a keyword.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID
Returns: Quality score details
Inputs: customer_id (required), ad_group_id (required), criterion_id (required). Returns: result
google_ads_get_optimization_scoreA
Get the account's optimization score (0-100%).
The optimization score represents how well your account is set up to perform. A score of 100% means your account is fully optimized based on Google's recommendations. Lower scores indicate room for improvement.
The score is calculated based on:
Available recommendations
Recommendation priority
Potential performance impact
Args: customer_id: Customer ID (without hyphens)
Returns: Optimization score with breakdown by recommendation type
Example: google_ads_get_optimization_score( customer_id="1234567890" )
Inputs: customer_id (required). Returns: result
google_ads_get_recommendation_historyA
Get history of applied and dismissed recommendations.
This shows what recommendations were applied or dismissed in a given time period, along with who made the changes.
Args: customer_id: Customer ID (without hyphens) start_date: Start date (YYYY-MM-DD) end_date: End date (YYYY-MM-DD)
Returns: Recommendation change history
Example: google_ads_get_recommendation_history( customer_id="1234567890", start_date="2025-11-01", end_date="2025-12-16" )
Inputs: customer_id (required), start_date (required), end_date (required). Returns: result
google_ads_get_recommendation_insightsB
Get aggregate insights about recommendations and their potential impact.
This provides a high-level summary of all recommendations, grouped by type, with total projected impact across all recommendations.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter
Returns: Aggregate recommendation insights with total potential impact
Example: google_ads_get_recommendation_insights( customer_id="1234567890" )
Inputs: customer_id (required), campaign_id. Returns: result
google_ads_get_recommendationsA
Get optimization recommendations from Google Ads.
Google's AI analyzes your account and suggests specific optimizations to improve performance. Recommendations can include keyword additions, budget increases, bidding strategy changes, and more.
Args: customer_id: Customer ID (without hyphens) recommendation_types: Optional list of recommendation types to filter (e.g., ["KEYWORD", "CAMPAIGN_BUDGET", "TARGET_CPA_OPT_IN"]) campaign_id: Optional campaign ID to filter recommendations response_format: Output format (markdown or json)
Returns: List of recommendations with projected impact
Example: google_ads_get_recommendations( customer_id="1234567890", recommendation_types=["KEYWORD", "CAMPAIGN_BUDGET"] )
Common Recommendation Types:
KEYWORD: Add new keywords
CAMPAIGN_BUDGET: Increase budget
TARGET_CPA_OPT_IN: Switch to Target CPA bidding
TARGET_ROAS_OPT_IN: Switch to Target ROAS bidding
RESPONSIVE_SEARCH_AD: Create responsive search ads
KEYWORD_MATCH_TYPE: Change keyword match types
USE_BROAD_MATCH_KEYWORD: Use broad match keywords
Inputs: customer_id (required), recommendation_types, campaign_id, response_format. Returns: result
google_ads_get_search_terms_for_keywordC
Get search terms that triggered ads for keywords in an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Optional specific keyword criterion ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)
Returns: Search terms report with performance data
Inputs: customer_id (required), ad_group_id (required), criterion_id, date_range. Returns: result
google_ads_get_url_suffixesA
Get current Final URL suffixes and tracking URL templates for campaigns and their ad groups.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter to a specific campaign. If omitted, returns all enabled campaigns.
Returns: Formatted table of URL suffixes and tracking templates
Inputs: customer_id (required), campaign_id. Returns: result
google_ads_get_user_list_detailsA
Get detailed information about a specific user list.
Args: customer_id: Customer ID (without hyphens) user_list_id: User list ID
Returns: Detailed user list information
Example: google_ads_get_user_list_details( customer_id="1234567890", user_list_id="12345" )
Inputs: customer_id (required), user_list_id (required). Returns: result
google_ads_import_from_csvA
Import entities from CSV format.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) entity_type: Type to import (campaigns, keywords) csv_data: CSV formatted data
CSV Format for Campaigns:
Campaign Name,Budget,Type,Status
My Campaign,50.00,SEARCH,PAUSEDCSV Format for Keywords:
Ad Group ID,Keyword Text,Match Type,CPC Bid
12345678,running shoes,EXACT,2.50Returns: Import result with success/failure details
Example: google_ads_import_from_csv( customer_id="1234567890", entity_type="campaigns", csv_data="Campaign Name,Budget,Type\nTest Campaign,50.00,SEARCH" )
Inputs: customer_id (required), entity_type (required), csv_data (required). Returns: result
google_ads_initializeA
Initialize the Google Ads API connection with OAuth credentials.
This must be called before using any other Google Ads tools. Provide your developer token, OAuth2 credentials, and optionally an MCC login customer ID if you're accessing client accounts.
Args: developer_token: API developer token client_id: OAuth2 client ID client_secret: OAuth2 client secret refresh_token: OAuth2 refresh token login_customer_id: Optional MCC account ID (without hyphens)
Returns: Confirmation message with initialization status
Inputs: developer_token (required), client_id (required), client_secret (required), refresh_token (required), +1 more. Returns: result
google_ads_keyword_forecastA
Forecast traffic metrics for specific keywords.
Get projected impressions, clicks, and costs for keywords over a future time period.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) keywords_json: JSON array of keywords with text and match_type Example: [{"text": "running shoes", "match_type": "BROAD"}] location_ids: Comma-separated location criterion IDs (default: 2840 = US) language_id: Language criterion ID (default: 1000 = English) cpc_bid: CPC bid amount for forecast (default: 1.0) date_interval: Forecast period - NEXT_WEEK, NEXT_MONTH, or NEXT_QUARTER response_format: Output format (markdown or json)
Returns: Traffic forecast with projected metrics
Example: google_ads_keyword_forecast( customer_id="1234567890", keywords_json='[{"text": "running shoes", "match_type": "BROAD"}, {"text": "nike shoes", "match_type": "PHRASE"}]', cpc_bid=2.5, date_interval="NEXT_MONTH" )
Match Types: - BROAD: Matches variations and related searches - PHRASE: Matches phrase and close variants - EXACT: Matches exact keyword only
Date Intervals: - NEXT_WEEK: 7-day forecast - NEXT_MONTH: 30-day forecast - NEXT_QUARTER: 90-day forecast
Inputs: customer_id (required), keywords_json (required), location_ids, language_id, +3 more. Returns: result
google_ads_keyword_ideasA
Get keyword ideas from Google Ads Keyword Planner.
Generate keyword suggestions based on seed keywords or a webpage URL. Includes search volume, competition level, and bid estimates.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) seed_keywords: Comma-separated seed keywords (e.g., "running shoes,nike") page_url: Optional URL to extract keywords from location_ids: Comma-separated location criterion IDs (default: 2840 = US) language_id: Language criterion ID (default: 1000 = English) keyword_plan_network: Network - GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS, or YOUTUBE response_format: Output format (markdown or json)
Returns: Keyword ideas with metrics (search volume, competition, bids)
Example: google_ads_keyword_ideas( customer_id="1234567890", seed_keywords="running shoes,athletic footwear", location_ids="2840", # US language_id="1000" # English )
Common Location IDs: - 2840: United States - 2826: United Kingdom - 2124: Canada - 2036: Australia
Competition Levels: - LOW: Easy to rank for - MEDIUM: Moderate competition - HIGH: Very competitive
Inputs: customer_id (required), seed_keywords, page_url, location_ids, +3 more. Returns: result
google_ads_list_accountsA
List all Google Ads accounts accessible with current credentials.
Returns details about all accounts you have access to, including customer IDs, names, currency codes, and whether they are manager accounts.
Args: response_format: Output format: 'markdown' for readable or 'json' for structured data
Returns: List of accessible accounts with their details
Inputs: response_format. Returns: result
google_ads_list_ad_groupsA
List ad groups with optional filters.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter by status: Optional status to filter by (ENABLED, PAUSED)
Returns: List of ad groups with key metrics
Inputs: customer_id (required), campaign_id, status. Returns: result
google_ads_list_adsB
List all ads in an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID
Returns: List of ads with details
Inputs: customer_id (required), ad_group_id (required). Returns: result
google_ads_list_bid_adjustmentsB
List all bid adjustments for a campaign (devices, locations, demographics, ad schedule).
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID
Returns: All bid adjustments in markdown format
Example: google_ads_list_bid_adjustments( customer_id="1234567890", campaign_id="111111111" )
Inputs: customer_id (required), campaign_id (required). Returns: result
google_ads_list_bidding_strategiesA
List all portfolio bidding strategies in the account.
Args: customer_id: Customer ID (without hyphens)
Returns: List of all portfolio bidding strategies with basic info
Example: google_ads_list_bidding_strategies( customer_id="1234567890" )
Inputs: customer_id (required). Returns: result
google_ads_list_conversion_actionsC
List all conversion actions in the account.
Args: customer_id: Customer ID (without hyphens) include_removed: Include removed conversions response_format: Output format (markdown or json)
Returns: List of all conversion actions
Example: google_ads_list_conversion_actions( customer_id="1234567890" )
Inputs: customer_id (required), include_removed, response_format. Returns: result
google_ads_list_keywordsC
List all keywords in an ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID
Returns: List of keywords
Inputs: customer_id (required), ad_group_id (required). Returns: result
google_ads_list_user_listsA
List all user lists (audiences) in the account.
Args: customer_id: Customer ID (without hyphens) list_type: Optional filter by type (CRMBASED, RULE_BASED, SIMILAR, LOGICAL)
Returns: List of all user lists with details
Example: google_ads_list_user_lists( customer_id="1234567890", list_type="CRMBASED" )
Inputs: customer_id (required), list_type. Returns: result
google_ads_local_performanceA
Get performance metrics for Local campaigns.
Retrieves key performance indicators for local campaigns including impressions, clicks, conversions, and cost data.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID to filter (returns all if not specified) date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc.
Returns: Dictionary with local campaign performance data including: - campaigns: List of campaign metrics - total_campaigns: Number of local campaigns
Example:
Get performance for all local campaigns in the last 30 days:
google_ads_local_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Metrics Included: - Impressions: Ad views - Clicks: User clicks - CTR: Click-through rate - Cost: Total spend - Conversions: Local actions (visits, calls, directions) - Conversion Value: Value of conversions - View-Through Conversions: Conversions after viewing (no click)
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_opportunity_finderA
Find optimization opportunities across your Google Ads account.
Combines multiple analyses to identify:
Budget optimization opportunities
Wasted spend to eliminate
Performance improvement areas
Quick wins for immediate impact
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) opportunity_type: Type of opportunities to find (ALL, BUDGET, WASTE, PERFORMANCE)
Returns: Comprehensive opportunity analysis with prioritized recommendations
Example: google_ads_opportunity_finder( customer_id="1234567890", opportunity_type="ALL" )
Inputs: customer_id (required), opportunity_type. Returns: result
google_ads_performance_forecasterA
Predict future campaign performance based on historical trends.
Uses historical data to forecast:
Projected spend
Estimated conversions
Expected ROAS
Confidence intervals
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Campaign ID to forecast forecast_days: Number of days to forecast (7-90)
Returns: Performance forecast with confidence ranges
Example: google_ads_performance_forecaster( customer_id="1234567890", campaign_id="12345678", forecast_days=30 )
Inputs: customer_id (required), campaign_id (required), forecast_days. Returns: result
google_ads_performance_insightsA
Generate AI-powered performance insights for campaigns, ad groups, keywords, or ads.
Analyzes performance metrics and provides actionable recommendations for:
Low CTR (below industry benchmarks)
Low conversion rates
Low impression share
Low quality scores
High performers worthy of increased budget
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) entity_type: Entity to analyze - CAMPAIGN, AD_GROUP, KEYWORD, or AD entity_id: Optional specific entity ID (if not provided, analyzes all) date_range: Date range (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH)
Returns: Performance insights with AI-generated recommendations
Example: google_ads_performance_insights( customer_id="1234567890", entity_type="CAMPAIGN", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), entity_type, entity_id, date_range. Returns: result
google_ads_pmax_insightsC
Get performance insights for a Performance Max campaign.
Provides comprehensive metrics including all-conversions data which captures conversions across all Google properties.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Performance Max campaign ID date_range: Date range (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS)
Returns: Performance Max campaign insights
Example: google_ads_pmax_insights( customer_id="1234567890", campaign_id="12345678", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id (required), date_range. Returns: result
google_ads_recommendationsB
Get AI-powered optimization recommendations from Google.
Retrieve Google's automated recommendations for improving campaign performance, including keyword suggestions, bid adjustments, and budget recommendations.
Args: customer_id: Customer ID without hyphens recommendation_types: Filter by recommendation types (e.g., ['KEYWORD', 'TARGET_CPA_OPT']) limit: Maximum number of recommendations (1-100) response_format: Output format: 'markdown' or 'json'
Returns: List of actionable optimization recommendations
Inputs: customer_id (required), recommendation_types, limit, response_format. Returns: result
google_ads_search_google_audiencesA
Search for Google's predefined audiences (In-Market, Affinity).
Google provides hundreds of pre-built audience segments based on user interests and purchase intent. Search to find relevant audiences for your business.
Args: customer_id: Customer ID (without hyphens) search_term: Search term (e.g., "coffee", "fitness", "travel")
Returns: List of matching Google audiences
Example: google_ads_search_google_audiences( customer_id="1234567890", search_term="coffee" )
Common Categories:
In-Market: Users actively researching products (high purchase intent)
Affinity: Users with sustained interest in a topic
Custom Intent: Create your own based on keywords/URLs
Inputs: customer_id (required), search_term (required). Returns: result
google_ads_search_termsB
View actual search queries that triggered your ads.
Shows the search terms report with performance metrics to identify new keyword opportunities and negative keyword candidates.
Args: customer_id: Customer ID without hyphens campaign_id: Optional campaign ID to filter date_range: Date range for the report limit: Maximum number of search terms to return response_format: Output format: 'markdown' or 'json'
Returns: Search terms with performance metrics
Inputs: customer_id (required), campaign_id, date_range, limit, +1 more. Returns: result
google_ads_set_ad_group_url_suffixA
Set the Final URL suffix for an ad group. This overrides the campaign-level suffix for ads in this ad group.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID to update url_suffix: URL parameters to append (e.g., 'utm_source=google&utm_medium=cpc&sm_kw=removable-bollards'). Pass empty string to clear and inherit campaign suffix.
Returns: Success message with the applied suffix
Inputs: customer_id (required), ad_group_id (required), url_suffix (required). Returns: result
google_ads_set_ad_schedule_bid_adjustmentsA
Set bid adjustments for ad scheduling (dayparting).
Control when your ads show and adjust bids based on time of day and day of week. This is useful for targeting business hours, weekends, or other high-converting periods.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID schedules: List of schedule configurations, each containing: - day_of_week: Day (MONDAY, TUESDAY, etc.) - start_hour: Start hour (0-23) - start_minute: Start minute (0, 15, 30, 45) - end_hour: End hour (0-24) - end_minute: End minute (0, 15, 30, 45) - bid_modifier: Bid adjustment (0.1 to 10.0)
Returns: Success message with created schedules
Example: google_ads_set_ad_schedule_bid_adjustments( customer_id="1234567890", campaign_id="111111111", schedules=[ { "day_of_week": "MONDAY", "start_hour": 9, "start_minute": 0, "end_hour": 17, "end_minute": 0, "bid_modifier": 1.5 # Increase bids 50% during business hours }, { "day_of_week": "SATURDAY", "start_hour": 0, "start_minute": 0, "end_hour": 24, "end_minute": 0, "bid_modifier": 0.7 # Decrease bids 30% on weekends } ] )
Inputs: customer_id (required), campaign_id (required), schedules (required). Returns: result
google_ads_set_attribution_modelA
Set attribution model for a conversion action.
Attribution models determine how credit for conversions is assigned to touchpoints in the customer journey.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID attribution_model: Attribution model to use
Returns: Success message
Example: google_ads_set_attribution_model( customer_id="1234567890", conversion_action_id="12345", attribution_model="DATA_DRIVEN" )
Attribution Models:
LAST_CLICK: 100% credit to last click (default)
FIRST_CLICK: 100% credit to first click
LINEAR: Equal credit across all clicks
TIME_DECAY: More credit to recent clicks
POSITION_BASED: 40% first, 40% last, 20% middle
DATA_DRIVEN: Google's ML model (recommended, requires sufficient data)
Recommendation: Use DATA_DRIVEN for accounts with 300+ conversions/month.
Inputs: customer_id (required), conversion_action_id (required), attribution_model (required). Returns: result
google_ads_set_audience_exclusionsA
Exclude audiences from a campaign.
Prevent your ads from showing to specific audiences. Common use cases:
Exclude existing customers from acquisition campaigns
Exclude converters from remarketing campaigns
Exclude low-value segments
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID user_list_ids: List of user list IDs to exclude
Returns: Success message
Example: google_ads_set_audience_exclusions( customer_id="1234567890", campaign_id="111111111", user_list_ids=["12345", "12346", "12347"] )
Use Case: Exclude "Past Purchasers" list from new customer acquisition campaign
Inputs: customer_id (required), campaign_id (required), user_list_ids (required). Returns: result
google_ads_set_audience_signalsA
Configure audience signals and search themes for a Performance Max asset group.
Search themes tell Google's AI what topics/keywords are relevant. Audience signals help Google's AI understand who your ideal customers are. Both are optional - provide whichever you need.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) asset_group_id: Asset group ID search_themes: List of search theme strings (max 25 per asset group) audience_segments: List of audience resource names
Example: google_ads_set_audience_signals( customer_id="1234567890", asset_group_id="12345678", search_themes=["escape room brisbane", "things to do brisbane"], audience_segments=["customers/1234567890/userLists/123"] )
Inputs: customer_id (required), asset_group_id (required), search_themes, audience_segments. Returns: result
google_ads_set_campaign_languagesA
Set language targeting for a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID language_codes: List of language constant IDs
Returns: Success message
Note: Common language IDs:
1000: English
1003: Spanish
1002: French
1001: German
1005: Chinese (Simplified)
Inputs: customer_id (required), campaign_id (required), language_codes (required). Returns: result
google_ads_set_campaign_locationsA
Set location targeting for a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID location_ids: List of geo target constant IDs to target negative_location_ids: List of geo target constant IDs to exclude (optional)
Returns: Success message
Note: Common location IDs:
2840: United States
2826: United Kingdom
2124: Canada
2036: Australia Use Google Ads location targeting tool to find specific IDs
Inputs: customer_id (required), campaign_id (required), location_ids (required), negative_location_ids. Returns: result
google_ads_set_campaign_scheduleA
Set ad scheduling (dayparting) for a campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID schedules: List of schedule dictionaries with: - day_of_week: Day name (MONDAY, TUESDAY, etc.) or numeric (0=Sunday, 6=Saturday) - start_hour: Hour to start (0-23) - start_minute: Minute to start (0, 15, 30, 45) - end_hour: Hour to end (0-24) - end_minute: Minute to end (0, 15, 30, 45) - bid_modifier: Optional bid adjustment (1.2 = +20%, 0.8 = -20%)
Returns: Success message with schedule summary
Example: schedules = [ { "day_of_week": "MONDAY", "start_hour": 9, "start_minute": 0, "end_hour": 17, "end_minute": 0, "bid_modifier": 1.2 } ]
Inputs: customer_id (required), campaign_id (required), schedules (required). Returns: result
google_ads_set_campaign_url_suffixA
Set the Final URL suffix for a campaign. The suffix is appended to all ad landing page URLs in this campaign.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update url_suffix: URL parameters to append (e.g., 'utm_source=google&utm_medium=cpc&sm_kw=bollards'). Pass empty string to clear.
Returns: Success message with the applied suffix
Inputs: customer_id (required), campaign_id (required), url_suffix (required). Returns: result
google_ads_set_device_bid_adjustmentsA
Set bid adjustments for different device types.
Bid modifiers allow you to increase or decrease bids based on the device used by the searcher. Values range from 0.1 (90% decrease) to 10.0 (900% increase).
Common adjustments:
1.0 = No change (default)
1.5 = Increase bids by 50%
0.7 = Decrease bids by 30%
0.1 = Decrease bids by 90% (effectively pause)
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID mobile_modifier: Bid modifier for mobile devices (0.1 to 10.0) desktop_modifier: Bid modifier for desktop devices (0.1 to 10.0) tablet_modifier: Bid modifier for tablet devices (0.1 to 10.0)
Returns: Success message with applied adjustments
Example: google_ads_set_device_bid_adjustments( customer_id="1234567890", campaign_id="111111111", mobile_modifier=1.3, # Increase mobile bids by 30% desktop_modifier=1.0, # No change for desktop tablet_modifier=0.8 # Decrease tablet bids by 20% )
Inputs: customer_id (required), campaign_id (required), mobile_modifier, desktop_modifier, +1 more. Returns: result
google_ads_shopping_feed_statusA
Check the status of your Google Merchant Center feed connection.
Verifies that your Merchant Center account is properly linked to Google Ads and that products can flow from Merchant Center to your shopping campaigns.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) merchant_center_id: Your Merchant Center account ID
Returns: Merchant Center feed status
Example: google_ads_shopping_feed_status( customer_id="1234567890", merchant_center_id="123456789" )
Inputs: customer_id (required), merchant_center_id (required). Returns: result
google_ads_shopping_performanceA
Get performance metrics for Shopping campaigns.
Provides detailed performance data including ROAS (return on ad spend), which is critical for shopping campaign optimization.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional specific shopping campaign ID date_range: Date range (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS)
Returns: Shopping campaign performance metrics
Example: google_ads_shopping_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_store_visitsA
Get store visit conversion data for Local campaigns.
Retrieves detailed store visit conversion metrics. Store visits are tracked when users who saw or clicked an ad subsequently visit a physical location.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID to filter (returns all if not specified) date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc.
Returns: Dictionary with store visit data including: - campaigns: List of campaigns with store visit conversions - total_store_visits: Total store visits across all campaigns - total_value: Total value of store visits - has_data: Whether any store visit data is available
Example:
Get store visit conversions for all local campaigns:
google_ads_store_visits( customer_id="1234567890", date_range="LAST_30_DAYS" )
Important Notes: - Requires Google My Business integration - Store visit data takes 4-6 weeks to accumulate - Uses probabilistic modeling based on location services - Aggregated and anonymized data for privacy
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_time_performanceB
Get performance by hour of day and day of week.
Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range
Returns: Performance breakdown by time
Example: google_ads_time_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )
Inputs: customer_id (required), campaign_id, date_range. Returns: result
google_ads_trend_analysisA
Analyze performance trends and detect anomalies over time.
Identifies:
Increasing/decreasing cost trends
Conversion performance trends
Anomalous days with unusual spending or performance
Provides daily performance data for visualization
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_id: Optional campaign ID filter (analyzes all campaigns if not provided) lookback_days: Number of days to analyze (7-90)
Returns: Trend analysis with anomaly detection
Example: google_ads_trend_analysis( customer_id="1234567890", lookback_days=30 )
Inputs: customer_id (required), campaign_id, lookback_days. Returns: result
google_ads_update_ad_groupB
Update ad group settings.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID to update ad_group_name: New ad group name (optional) status: New status (ENABLED, PAUSED, or REMOVED) (optional) cpc_bid: New CPC bid in currency units (optional)
Returns: Success message with updated fields
Inputs: customer_id (required), ad_group_id (required), ad_group_name, status, +1 more. Returns: result
google_ads_update_ad_group_bidB
Update ad group CPC bid.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID cpc_bid: New CPC bid in currency units (e.g., 1.50 for $1.50)
Returns: Success message with bid details
Inputs: customer_id (required), ad_group_id (required), cpc_bid (required). Returns: result
google_ads_update_ad_group_statusC
Update ad group status (enable, pause, or remove).
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID status: New status (ENABLED, PAUSED, or REMOVED)
Returns: Success message
Inputs: customer_id (required), ad_group_id (required), status (required). Returns: result
google_ads_update_ad_statusB
Update ad status (enable, pause, or remove).
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID status: New status (ENABLED, PAUSED, or REMOVED)
Returns: Success message
Inputs: customer_id (required), ad_group_id (required), ad_id (required), status (required). Returns: result
google_ads_update_bidding_strategyB
Update an existing portfolio bidding strategy's settings.
Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID to update strategy_name: New name for the strategy (optional) target_cpa: New target CPA in currency units (for TARGET_CPA strategies) target_roas: New target ROAS as decimal (for TARGET_ROAS strategies) target_impression_share: New target impression share 0.0-1.0 (for TARGET_IMPRESSION_SHARE) max_cpc_bid: New maximum CPC bid limit (for TARGET_IMPRESSION_SHARE)
Returns: Success message with updated configuration
Example: google_ads_update_bidding_strategy( customer_id="1234567890", bidding_strategy_id="12345", target_cpa=30.00 )
Inputs: customer_id (required), bidding_strategy_id (required), strategy_name, target_cpa, +3 more. Returns: result
google_ads_update_campaignB
Update campaign settings.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update campaign_name: New campaign name (optional) status: New status (ENABLED, PAUSED, or REMOVED) (optional) start_date: New start date in YYYY-MM-DD format (optional) end_date: New end date in YYYY-MM-DD format (optional)
Returns: Success message with updated fields
Inputs: customer_id (required), campaign_id (required), campaign_name, status, +2 more. Returns: result
google_ads_update_campaign_budget_v2A
Update campaign daily budget.
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID daily_budget: New daily budget in currency units (e.g., 100.00 for $100/day)
Returns: Success message with budget details
Inputs: customer_id (required), campaign_id (required), daily_budget (required). Returns: result
google_ads_update_campaign_status_v2B
Update campaign status (enable, pause, or remove).
Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID status: New status (ENABLED, PAUSED, or REMOVED)
Returns: Success message
Inputs: customer_id (required), campaign_id (required), status (required). Returns: result
google_ads_update_conversion_actionB
Update conversion action settings.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID to update conversion_value: New default value status: New status (ENABLED, PAUSED, REMOVED)
Returns: Success message
Example: google_ads_update_conversion_action( customer_id="1234567890", conversion_action_id="12345", conversion_value=75.00, status="ENABLED" )
Inputs: customer_id (required), conversion_action_id (required), conversion_value, status. Returns: result
google_ads_update_keyword_bidA
Update keyword CPC bid.
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID cpc_bid: New CPC bid in currency units (e.g., 1.50 for $1.50)
Returns: Success message
Inputs: customer_id (required), ad_group_id (required), criterion_id (required), cpc_bid (required). Returns: result
google_ads_update_keyword_statusB
Update keyword status (enable, pause, or remove).
Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID status: New status (ENABLED, PAUSED, or REMOVED)
Returns: Success message
Inputs: customer_id (required), ad_group_id (required), criterion_id (required), status (required). Returns: result
google_ads_upload_call_conversionsB
Upload call conversion data for phone calls that converted.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Call conversion action ID call_conversions: List with: - caller_id: Phone number that called (E.164 format: +12345678900) - call_start_date_time: When call started - conversion_date_time: When call qualified as conversion - conversion_value: Optional conversion value - currency_code: Optional currency
Returns: Upload success message
Example: google_ads_upload_call_conversions( customer_id="1234567890", conversion_action_id="12345", call_conversions=[ { "caller_id": "+12025551234", "call_start_date_time": "2025-12-15 10:30:00-08:00", "conversion_date_time": "2025-12-15 10:35:00-08:00", "conversion_value": 500.00, "currency_code": "USD" } ] )
Inputs: customer_id (required), conversion_action_id (required), call_conversions (required). Returns: result
google_ads_upload_customer_matchA
Upload Customer Match data (emails, phones, addresses).
Customer Match allows you to use your customer data to reach them on Google Search, YouTube, Gmail, and Display Network. Data is hashed before upload for privacy.
You can either upload to an existing list (provide user_list_id) or create a new list (provide list_name).
Args: customer_id: Customer ID (without hyphens) user_list_id: Existing user list ID to upload to (optional) list_name: Name for new list (required if user_list_id not provided) emails: List of email addresses phones: List of phone numbers (E.164 format recommended: +12345678900) first_names: List of first names (must match emails/phones index) last_names: List of last names (must match emails/phones index) countries: List of country codes (e.g., "US", "UK") zip_codes: List of postal codes
Returns: Success message with upload job details
Example: google_ads_upload_customer_match( customer_id="1234567890", list_name="Email Newsletter Subscribers", emails=[ "customer1@example.com", "customer2@example.com", "customer3@example.com" ] )
Privacy Note: All data is automatically hashed with SHA256 before upload. Google cannot see the original data.
Match Rate: Typically 30-70% of uploaded records will match to Google users.
Inputs: customer_id (required), user_list_id, list_name, emails, +5 more. Returns: result
google_ads_upload_offline_conversionsA
Upload offline conversion data (CRM conversions, phone orders, store visits).
Use this to import conversions that happen offline but originated from Google Ads clicks. You must have the GCLID (Google Click ID) for each conversion.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID (must be IMPORT origin) conversions: List of conversion dictionaries with: - gclid: Google Click ID (required) - conversion_date_time: When conversion occurred (required) Format: "YYYY-MM-DD HH:MM:SS+TZ" (e.g., "2025-12-16 14:30:00-08:00") - conversion_value: Conversion value (optional) - currency_code: Currency code (optional, e.g., "USD")
Returns: Upload success message with count
Example: google_ads_upload_offline_conversions( customer_id="1234567890", conversion_action_id="12345", conversions=[ { "gclid": "Cj0KCQiA...", "conversion_date_time": "2025-12-15 10:30:00-08:00", "conversion_value": 150.00, "currency_code": "USD" }, { "gclid": "Cj0KCQiB...", "conversion_date_time": "2025-12-15 14:20:00-08:00", "conversion_value": 200.00, "currency_code": "USD" } ] )
GCLID Capture: Add {lpurl}?gclid={gclid} to landing page URLs to capture GCLID.
Inputs: customer_id (required), conversion_action_id (required), conversions (required). Returns: result
google_ads_upload_pmax_assetsB
Upload text assets to a Performance Max asset group.
Text assets include headlines, descriptions, and long headlines. Google's AI will mix and match these across different placements. All parameters are optional - provide only the asset types you want to add.
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) asset_group_id: Asset group ID headlines: List of headlines (max 30 chars each, up to 15 per asset group) descriptions: List of descriptions (max 90 chars each, up to 5 per asset group) long_headlines: List of long headlines (max 90 chars each, up to 5 per asset group)
Example: google_ads_upload_pmax_assets( customer_id="1234567890", asset_group_id="12345678", headlines=["Buy Now", "Free Shipping", "Best Prices"], descriptions=["Shop the latest products", "Quality guaranteed"], long_headlines=["Shop Our Complete Product Line Today"] )
Inputs: customer_id (required), asset_group_id (required), headlines, descriptions, +1 more. Returns: result
google_ads_upload_store_salesA
Upload store sales data (in-store purchases from online clicks).
This is a specialized form of offline conversion upload for retail businesses tracking in-store purchases that originated from online ads.
Args: customer_id: Customer ID (without hyphens) conversion_action_id: Store sales conversion action ID store_sales: List of sales with gclid, timestamp, value
Returns: Upload success message
Example: google_ads_upload_store_sales( customer_id="1234567890", conversion_action_id="12345", store_sales=[ { "gclid": "Cj0KCQiA...", "conversion_date_time": "2025-12-15 15:45:00-08:00", "conversion_value": 85.50, "currency_code": "USD" } ] )
Note: This uses the same upload mechanism as offline conversions.
Inputs: customer_id (required), conversion_action_id (required), store_sales (required). Returns: result
google_ads_wasted_spend_analysisA
Identify sources of wasted ad spend and optimization opportunities.
Analyzes:
Keywords with high cost but no conversions
Poor match type usage
Inefficient spending patterns
Specific recommendations to reduce waste
Args: customer_id: Google Ads customer ID (10 digits, no hyphens) date_range: Date range for analysis (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS) min_cost: Minimum cost threshold for analysis (default: $10)
Returns: Wasted spend analysis with actionable recommendations
Example: google_ads_wasted_spend_analysis( customer_id="1234567890", date_range="LAST_30_DAYS", min_cost=20.0 )
Inputs: customer_id (required), date_range, min_cost. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 142 tools
Most tools have clear, distinct purposes with good descriptions, but there is overlap among multiple status update tools (batch_status_change, bulk_update_ad_group_status, update_ad_group_status, etc.) and among various performance report tools that operate at different levels.
Tool names consistently use the `google_ads_verb_noun` pattern, with only minor deviations like `google_ads_recommendations` alongside `google_ads_get_recommendations`. The naming is clear and predictable overall.
142 tools is very large but justified by the complexity of Google Ads. However, there is significant redundancy (e.g., multiple ways to update status) that could be consolidated, making the count feel excessive for an MCP server.
The tool surface covers nearly all major areas of Google Ads management, including campaigns, ad groups, keywords, extensions, conversions, recommendations, and shopping. Minor gaps exist, such as lack of tools for listing/updating ad extensions beyond creation.
Maintenance
Related MCP Connectors
Google Ads analysis and operations — read performance, manage keywords, bids, and campaigns.
Run Google Ads, Meta, TikTok, LinkedIn, GA4 & Search Console from chat. Changes wait for approval.
Ask Claude about your Google Ads: campaign performance, wasted search terms, GAQL reports.
Manage Google, Meta, TikTok, Snapchat and LinkedIn ads, plus GA4, Tag Manager and Search Console, by chat from Claude or ChatGPT. Spend increases need your confirmation first.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables comprehensive Google Ads campaign management and analytics through the Google Ads API. Supports querying campaigns, ad groups, keywords, performance metrics, and executing custom GAQL queries with token-efficient implementation.-
- FlicenseNot gradedqualityDmaintenanceEnables comprehensive management of Google Ads campaigns through natural language, including campaign creation, ad group management, keyword operations, Performance Max campaigns, conversion tracking, and performance insights with support for multiple accounts.3-
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive access to Google Ads API v20, enabling AI assistants to manage campaigns, accounts, assets, and reporting through natural language. It features automatic retry logic, GAQL query support, and advanced functionality for Performance Max and Demand Gen campaigns.11MIT
- AlicenseBqualityCmaintenanceEnables full read/write control of Google Ads accounts—managing campaigns, ad groups, ads, keywords, Performance Max, budgets, targeting, and performance reporting through natural language. Supports Search, Display, Video, and Demand Gen campaign types with flexible GAQL querying and comprehensive reporting.471Apache 2.0