Overview

The Google Ads MCP (Model Context Protocol) Server is a powerful integration that provides comprehensive access to your Google Ads account data and performance metrics. This server enables you to retrieve detailed campaign insights, analyze keyword performance, track conversions, and execute custom queries using Google's advanced GAQL (Google Ads Query Language).

Key Benefits:

• Complete Campaign Access: Connect to all your Google Ads accounts and retrieve comprehensive advertising data

• Advanced Query Capabilities: Execute any custom GAQL query for specialized analysis

• Real-time Performance Data: Access up-to-date campaign metrics, costs, and conversion data

• Flexible Reporting: Create custom reports with any combination of metrics and dimensions

• Multi-Account Management: Manage and analyze multiple Google Ads accounts, including manager account hierarchies

Tool Reference

1. List Google Ads Accounts

Purpose: Discover and access all Google Ads accounts available to your credentials.

What it does: Retrieves a complete list of all Google Ads accounts you have access to, including both directly accessible accounts and managed accounts through manager account hierarchies. This tool automatically identifies manager accounts and their sub-accounts.

Key Parameters:

• No required parameters - automatically discovers all accessible accounts

Account Information Retrieved:

• Account ID: Unique Google Ads customer ID (required for all other operations)

• Account Name: Descriptive name of the account

• Access Type: Direct access or managed through parent account

• Manager Status: Whether the account is a manager account

• Hierarchy Level: Account level in manager account structure

• Parent ID: Manager account ID (for managed accounts)

Sample Use Cases:

• Initial setup to discover available accounts

• Account access verification and auditing

• Understanding account hierarchy structure

• Identifying which accounts require manager_id parameter

Example Request:

Example Output:

{
  "accounts": [
    {
      "id": "1234567890",
      "name": "My Business - Main Account",
      "access_type": "direct",
      "level": 0
    },
    {
      "id": "9876543210",
      "name": "Client A - Shopping Campaigns",
      "access_type": "managed", 
      "parent_id": "1234567890",
      "level": 1
    },
    {
      "id": "5555666677",
      "name": "My Business - Manager Account",
      "access_type": "direct",
      "level": 0
    }
  ]
}

2. Execute Custom GAQL Queries

Purpose: Run any custom Google Ads Query Language (GAQL) query to retrieve specific advertising data and metrics.

What it does: Provides unlimited flexibility to query any Google Ads data using GAQL, Google's SQL-like query language designed specifically for advertising data. This is the most powerful tool for custom analysis and reporting.

Key Parameters:

• customer_id (required): Google Ads customer ID as string (10 digits, no dashes)

• query (required): Valid GAQL query to execute

• manager_id (optional): Required for managed accounts - use parent account ID

GAQL Query Structure:

SELECT field1, field2, metrics.metric_name
FROM resource_type
WHERE condition
ORDER BY field [ASC|DESC]
LIMIT

Common GAQL Query Patterns

Campaign Performance Analysis

Purpose: Analyze overall campaign effectiveness and ROI.

Sample Use Cases:

• Campaign performance monitoring

• Budget allocation optimization

• ROI analysis and reporting

• Campaign comparison and benchmarking

Basic Campaign Metrics Query:

SELECT 
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.ctr
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC

Example Output:

{
  "results": [
    {
      "campaign": {
        "id": "12345678901",
        "name": "Summer Sale Campaign",
        "status": "ENABLED"
      },
      "metrics": {
        "impressions": "125000",
        "clicks": "3200",
        "costMicros": "450000000",
        "conversions": 85.0,
        "conversionsValue": 12750.0,
        "ctr": 0.0256
      }
    }
  ]
}

Keyword Performance Analysis

Purpose: Analyze keyword effectiveness and search term performance.

Sample Use Cases:

• Keyword bid optimization

• Search term discovery

• Match type performance analysis

• Negative keyword identification

Keyword Performance Query:

SELECT 
  campaign.id,
  campaign.name,
  ad_group.name,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.impressions,
  metrics.clicks,
  metrics.average_cpc,
  metrics.conversions,
  metrics.cost_micros
FROM keyword_view 
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.clicks DESC
LIMIT 50

Example Output:

{
  "results": [
    {
      "campaign": {
        "id": "12345678901", 
        "name": "Brand Campaign"
      },
      "adGroup": {
        "name": "Core Keywords"
      },
      "adGroupCriterion": {
        "keyword": {
          "text": "premium widgets",
          "matchType": "PHRASE"
        }
      },
      "metrics": {
        "impressions": "8500",
        "clicks": "340",
        "averageCpc": 125000,
        "conversions": 12.0,
        "costMicros": "42500000"
      }
    }
  ]
}

Conversion and Revenue Tracking

Purpose: Monitor conversion performance and revenue attribution.

Sample Use Cases:

• ROI and ROAS calculation

• Conversion rate optimization

• Revenue attribution analysis

• Performance-based budget allocation

Conversion Revenue Query:

SELECT
  campaign.id,
  campaign.name,
  ad_group.name,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.all_conversions,
  metrics.all_conversions_value
FROM ad_group
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions > 0
ORDER BY metrics.conversions_value DESC

Key Revenue Metrics:

• metrics.conversions_value: Direct conversion revenue (primary metric for ROI)

• metrics.all_conversions_value: Total attributed revenue (includes view-through)

• metrics.cost_micros: Cost in micros (divide by 1,000,000 for actual cost)

Search Term Insights

Purpose: Discover which search terms are triggering your ads and driving performance.

Sample Use Cases:

• Search term discovery for keyword expansion

• Negative keyword identification

• Match type optimization

• Campaign targeting refinement

Search Term Analysis Query:

SELECT
  campaign.id,
  campaign.name,
  campaign_search_term_insight.category_label,
  metrics.clicks,
  metrics.impressions,
  metrics.conversions,
  metrics.cost_micros,
  metrics.ctr
FROM campaign_search_term_insight
WHERE campaign.id = '12345678901'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 100

Budget and Cost Analysis

Purpose: Analyze budget utilization and cost efficiency across campaigns.

Sample Use Cases:

• Budget allocation optimization

• Cost-per-acquisition monitoring

• Spend pattern analysis

• Budget utilization tracking

Budget Analysis Query:

SELECT
  campaign.id,
  campaign.name,
  campaign_budget.amount_micros,
  metrics.cost_micros,
  metrics.average_cpc,
  metrics.cost_per_conversion
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC

Device and Geographic Performance

Purpose: Analyze performance across different devices and geographic locations.

Sample Use Cases:

• Device bid adjustments

• Geographic targeting optimization

• Mobile vs desktop performance analysis

• Location-based budget allocation

Device Performance Query:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_micros,
  metrics.ctr
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY segments.device, metrics.clicks DESC

Geographic Performance Query:

SELECT
  campaign.id,
  campaign.name,
  geographic_view.country_criterion_id,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_micros
FROM geographic_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.clicks > 10
ORDER BY metrics.conversions DESC

Advanced GAQL Features

Date Range Options

Relative Date Ranges:

• LAST_7_DAYS - Previous 7 days

• LAST_30_DAYS - Previous 30 days

• LAST_WEEK - Previous complete week

• LAST_MONTH - Previous complete month

• THIS_MONTH - Current month to date

• THIS_YEAR - Current year to date

Specific Date Ranges:

WHERE segments.date BETWEEN '2024-01-01' AND '2024-01-31'

Filtering and Conditions

Numeric Filters:

WHERE metrics.clicks > 100
WHERE metrics.cost_micros < 5000000  -- Less than $5
WHERE metrics.conversions >= 1

Text Filters:

WHERE campaign.name LIKE '%Brand%'
WHERE campaign.name NOT LIKE '%Test%'
WHERE ad_group.name CONTAINS 'Keywords'

Status Filters:

WHERE campaign.status = 'ENABLED'
WHERE ad_group.status IN ('ENABLED', 'PAUSED')

Sorting and Limiting

Sorting Options:

ORDER BY metrics.clicks DESC
ORDER BY campaign.name ASC
ORDER BY metrics.cost_micros DESC, metrics.conversions DESC

Result Limiting:

LIMIT 50  -- Return top 50 results
LIMIT 100 -- Return top 100 results

Resource Types and Key Fields

Campaign Resource

• campaign.id - Unique campaign identifier

• campaign.name - Campaign name

• campaign.status - ENABLED, PAUSED, REMOVED

• campaign.advertising_channel_type - SEARCH, DISPLAY, SHOPPING, etc.

Ad Group Resource

• ad_group.id - Unique ad group identifier

• ad_group.name - Ad group name

• ad_group.status - ENABLED, PAUSED, REMOVED

• ad_group.type - STANDARD, DISPLAY_STANDARD, etc.

Keyword View Resource

• ad_group_criterion.keyword.text - Keyword text

• ad_group_criterion.keyword.match_type - EXACT, PHRASE, BROAD

• ad_group_criterion.status - ENABLED, PAUSED, REMOVED

Common Metrics

• metrics.impressions - Number of times ads were shown

• metrics.clicks - Number of clicks received

• metrics.cost_micros - Cost in micros (divide by 1,000,000 for dollars)

• metrics.conversions - Number of conversions

• metrics.conversions_value - Conversion value in account currency

• metrics.ctr - Click-through rate (clicks/impressions)

• metrics.average_cpc - Average cost per click in micros

Segment Fields

• segments.date - Date of the data (YYYY-MM-DD format)

• segments.device - MOBILE, DESKTOP, TABLET

• segments.day_of_week - MONDAY, TUESDAY, etc.

• segments.hour - Hour of day (0-23)

Best Practices

Query Optimization

• Always include date ranges: Use specific date ranges rather than open-ended queries

• Filter early: Apply WHERE clauses to reduce data volume

• Limit results: Use LIMIT to prevent overwhelming responses

• Select specific fields: Only request needed fields to improve performance

Account Management

• Use List Accounts first: Always discover accounts before running queries

• Check managed accounts: Use manager_id parameter for managed accounts

• Validate customer IDs: Ensure customer_id is formatted as 10-digit string

Data Analysis

• Understand micros: Many cost fields are in micros (divide by 1,000,000)

• Use appropriate metrics: Choose between conversions vs all_conversions based on needs

• Consider attribution: Understand difference between direct and attributed conversions

Error Prevention

• Required fields: Include campaign.id when querying campaign-related resources

• Valid resources: Use correct resource names (keyword_view, not keywords)

• Date constraints: All date ranges must be finite

• Text matching: Use LIKE '%text%' instead of CONTAINS

Getting Started

Prerequisites

• Active Google Ads account with API access enabled

• Google Cloud Console project with Google Ads API enabled

• Valid OAuth2 credentials with appropriate scopes

• Developer token from Google Ads (required for API access)

Required API Scopes

• https://www.googleapis.com/auth/adwords - Full Google Ads API access

Basic Workflow

1. Account Discovery: Start with "List Google Ads Accounts" to identify available accounts

2. Account Structure: Note which accounts are managed (require manager_id parameter)

3. Basic Analysis: Run simple campaign performance queries

4. Advanced Analysis: Create custom GAQL queries for specific needs

5. Performance Monitoring: Set up regular queries for ongoing optimization

Sample Getting Started Queries

1. Verify Account Access:

SELECT customer.descriptive_name, customer.id 
FROM

2. List Active Campaigns:

SELECT campaign.id, campaign.name, campaign.status
FROM campaign
WHERE campaign.status = 'ENABLED'

3. Basic Performance Overview:

SELECT 
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.cost_micros DESC
LIMIT 10

Common Use Case Examples

Daily Performance Monitoring

SELECT 
  campaign.name,
  segments.date,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY segments.date DESC, metrics.cost_micros DESC

Keyword Optimization Analysis

SELECT 
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.clicks,
  metrics.average_cpc,
  metrics.conversions,
  metrics.cost_per_conversion
FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.clicks > 10
ORDER BY metrics.cost_per_conversion ASC
LIMIT 50

Budget Utilization Report

SELECT 
  campaign.name,
  campaign_budget.amount_micros,
  metrics.cost_micros,
  (metrics.cost_micros / campaign_budget.amount_micros * 100) as budget_utilization_percent
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY budget_utilization_percent DESC

Conversion Performance by Device

SELECT 
  segments.device,
  SUM(metrics.conversions) as total_conversions,
  SUM(metrics.cost_micros) as total_cost,
  AVG(metrics.cost_per_conversion) as avg_cost_per_conversion
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions > 0
GROUP BY segments.device
ORDER BY total_conversions DESC

Troubleshooting

Common Error Messages

"Customer not found" or "not accessible"

• Verify customer_id is correct 10-digit format

• For managed accounts, include manager_id parameter

• Check account access permissions

"Invalid query" or "syntax error"

• Verify GAQL syntax is correct

• Check field names and resource types

• Ensure proper use of quotes and operators

"Permission denied"

• Check API credentials and developer token

• Verify OAuth2 scopes include adwords access

• Ensure account has API access enabled

"Field not found"

• Use correct field names (e.g., ad_group_criterion.keyword.text, not keyword.text)

• Check resource-specific field availability

• Refer to Google Ads API documentation for valid fields

Data Quality Issues

Missing Recent Data:

• Google Ads data typically has 3-hour delay for most metrics

• Conversion data may have longer delays

• Use appropriate date ranges

Unexpected Cost Values:

• Remember cost fields are in micros (divide by 1,000,000)

• Check currency settings in account

• Verify date range and filtering

Zero Conversions:

• Check conversion tracking setup

• Verify attribution windows

• Consider using all_conversions for broader view

Performance Issues

Slow Query Response:

• Limit date ranges to reasonable periods

• Use LIMIT clause to restrict result size

• Filter data early with WHERE clauses

• Request only necessary fields

API Rate Limits:

• Implement proper request spacing

• Use efficient queries to minimize API calls

• Cache frequently accessed data

Support and Resources

Getting Help

• Review Google Ads API documentation for GAQL syntax

• Check Google Ads Help Center for account setup issues

• Validate queries with smaller date ranges first

• Test account access with simple customer queries

Error Reporting

The server provides detailed error information including:

• Google Ads API error codes and descriptions

• GAQL syntax validation messages

• Account access and permission status

• Suggested resolution steps

Advanced Features

• Manager Account Hierarchies: Handle complex account structures

• Custom Metrics: Access all available Google Ads metrics

• Flexible Dimensions: Segment data by any available dimension

• Real-time Data: Access near real-time advertising performance

All tools include comprehensive error handling and will return structured error information to help diagnose and resolve issues quickly.