Google Ads

Google Ads campaign management with GAQL query support

30 tools available

Installation

Claude Desktop

{
  "mcpServers": {
    "hopkin-google-ads": {
      "url": "https://google.mcp.hopkin.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

CLI

npm install -g @hopkin/cli
hopkin auth set-key hpk_live_...
hopkin google ping

Platform Overview

The Google Ads MCP server enables Claude to manage and analyze Google Ads campaigns using the Google Ads API with full GAQL (Google Ads Query Language) support. It provides access to campaign management, keyword and search term analysis, performance reporting, geographic insights, conversion tracking, and asset-level performance breakdowns — allowing you to retrieve comprehensive advertising data and insights across multiple reporting levels.

Your prompt → Claude + Hopkin → Google Ads API
                                    ↓
                              Campaign Data
                              Keyword Performance
                              Search Terms & Categories
                              Geographic Performance
                              Asset Reports
                              Conversion Actions

Common Workflows

Performance Reporting

"Show me the performance of all my campaigns over the last 30 days, broken down by device type."

Uses google_ads_get_performance_report with segments=['device'] to retrieve funnel metrics (impressions, clicks, cost, conversions) and per-conversion-action breakdown. Returns complete performance data with search impression share metrics.

"What's my account-level summary for the last 7 days? I need impressions, clicks, cost, and conversions."

Calls google_ads_get_account_summary with date_preset='LAST_7_DAYS' for a standardized cross-platform comparison view. Always fetches fresh data with normalized metrics identical to Meta Ads summaries.

"Break down my campaign performance by daily trends for the last week."

Uses google_ads_get_performance_report with segments=['date'] and date_preset='LAST_7_DAYS' at campaign level to show day-by-day performance variation.

Campaign & Ad Group Management

"List all my active campaigns."

Calls google_ads_list_campaigns with status=['ENABLED'] to get enabled campaigns with caching and background refresh. Pass refresh=true for real-time data.

"Show me all ad groups in campaign ABC123."

Uses google_ads_list_ad_groups with campaign_id='ABC123' to retrieve all ad groups and their status information with pagination support.

"What ads are in ad group XYZ789?"

Calls google_ads_list_ads with ad_group_id='XYZ789' to list all ads in that ad group, including status and creative details.

Keyword & Search Term Analysis

"Which keywords are driving the most conversions this month?"

Uses google_ads_get_keyword_performance with date_preset='LAST_30_DAYS' and order_by='conversions' to rank keywords by conversion volume. Includes quality score, match type, and ad network breakdown.

"Show me the search terms that aren't covered by my current keywords."

Calls google_ads_get_search_terms_report with date_preset='LAST_7_DAYS' and search_term_status=['NONE'] (unmapped) to identify gaps. Optionally include landing page data with include_landing_pages=true.

"What search terms are driving clicks on Search Partners?"

Uses google_ads_get_search_terms_report with segments=['ad_network_type'] to see which channels (SEARCH vs SEARCH_PARTNERS) drove each term.

Geographic & Audience Insights

"Which countries are my top performers by spend?"

Calls google_ads_get_geo_performance with geo_level='country' and date_preset='LAST_30_DAYS' to compare performance across countries with automatic location name resolution.

"What's the city-level performance breakdown for my campaigns in the last 7 days?"

Uses google_ads_get_geo_performance with geo_level='geo_target_city' and level='CAMPAIGN' to segment by city with both AREA_OF_INTEREST and LOCATION_OF_PRESENCE data.

Recipes

"Analyze my Performance Max campaign's channel breakdown for the last 30 days. Which channel (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER) is driving the most conversions?"

Calls google_ads_get_insights with campaign_id='your_pmax_id', segments=['ad_network_type'], and default metrics to see channel-level performance. This reveals which ad networks within PMax are performing best and helps inform budget allocation.

"Generate a search impression share diagnostic for my brand campaigns this week. I need top impression share, budget lost share, and rank lost share at the campaign level."

Uses google_ads_get_insights with level='CAMPAIGN', date_preset='LAST_7_DAYS', metrics=['search_impression_share', 'search_top_impression_share', 'search_budget_lost_impression_share', 'search_rank_lost_impression_share'] to diagnose competitive gaps and budget constraints.

"Show me all my assets (headlines, descriptions, images) and how each is performing. Which assets get the most impressions and conversions?"

Calls google_ads_get_asset_report with date_preset='LAST_30_DAYS' to break down performance by creative asset at all hierarchy levels. Optionally request include_change_history=true to see asset creation/edit events.

"Find search terms that are converting well but aren't yet mapped to any keyword. What landing pages are they going to?"

Uses google_ads_get_search_terms_report with search_term_status=['NONE'], include_landing_pages=true, and order_by='conversions' to identify high-value unmapped terms and their landing page destinations.

"Compare conversion action performance across my account. Which conversion actions contribute the most value this month?"

Calls google_ads_get_insights with segments=['conversion_action_name'], metrics=['all_conversions', 'all_conversions_value', 'value_per_all_conversions'], and date_preset='LAST_30_DAYS'. The tool auto-filters incompatible cost-based metrics and returns a warning.

"Audit my negative keywords. Are there any aggressive broad match negatives at the campaign level that might be blocking good searches?"

Uses google_ads_list_negative_keywords with level='CAMPAIGN' and match_type=['BROAD'] to identify potentially over-broad negative keyword exclusions that could suppress valuable traffic.

"I'm managing multiple child accounts under my MCC. Show me the performance summary for each child account."

Calls google_ads_get_account_summary for each child account using login_customer_id='your_mcc_id' and the child customer_id to aggregate normalized metrics across the managed portfolio.

Tips

GAQL queries and segments: When using google_ads_get_insights, specify custom metrics and segments to unlock flexibility the performance report doesn't offer. Use ad_network_type segment to break down Performance Max by channel. Segments must be compatible with your metrics — the tool auto-removes conflicting cost-based metrics when conversion_action segments are used and returns warnings about what was filtered.

MCC (Manager Account) hierarchy: If you're querying child accounts under an MCC, always pass login_customer_id with the parent MCC's Customer ID. Without it, API calls to managed accounts fail with permission errors. Use google_ads_list_mcc_child_accounts to discover children of a specific MCC.

Geographic performance constraints: The geographic_view resource requires exactly one geo level per query (country, city, region, state, metro, etc.). Combining multiple geo levels silently loses data. Criterion IDs are auto-resolved to human-readable location names, and both AREA_OF_INTEREST and LOCATION_OF_PRESENCE location types are always returned.

Caching and freshness: List tools (accounts, campaigns, ad groups, ads) use cache-first fetching with background refresh (data is fresh within minutes). Pass refresh=true when you need real-time data. Reporting tools (insights, performance report, keyword/search term metrics, geo performance) always fetch live data from the API — no caching.

Tools

account-summary

`google_ads_get_account_summary` Get Google Ads Account Summary

Read-onlyIdempotentOpen-world

Standardized account-level performance summary for cross-platform comparison. Returns normalized metrics identical to meta_ads_get_account_summary plus the supported Demand Gen Platform Comparable conversion family, with per-conversion-action breakdown. Preferred over insights or performance report for quick account overviews. Always fetches fresh data.

Parameter	Type	Description
`customer_id` required	`string`	The Google Ads Customer ID (10 digits, with or without dashes)
`reason` required	`string`	Why this tool call is needed

3 optional parameters

Parameter	Type	Description
`login_customer_id`	`string`	MCC (Manager) Customer ID; required for managed accounts
`date_preset`	`string`	Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
`date_range`	`object`	Custom date range {start_date, end_date} in YYYY-MM-DD

Parameter	Type	Description
`customer_id`	`string`	Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination.
`customer_ids`	`array`	Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination.
`refresh`	`boolean`	Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
`cursor`	`string`	Pagination cursor from previous response
`search`	`string`	Search accounts by name (case-insensitive partial match)
`limit`	`integer`	Number of accounts per page (default: 20, max: 100)
`label_filter`	`array`	Filter by labels. Accepts an array whose entries are any of: label name (e.g. "Big Boom"), bare label ID (e.g. "9876543210"), or full label resource name (e.g. "customers/1234567890/labels/9876543210"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error.

Parameter	Type	Description
`mcc_id` required	`string`	The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)
`reason` required	`string`	Why this tool call is needed

Parameter	Type	Description
`search`	`string`	Search child accounts by name or customer ID (case-insensitive partial match)
`limit`	`integer`	Number of accounts per page (default: 20, max: 100)
`cursor`	`string`	Pagination cursor from previous response
`refresh`	`boolean`	Force a fresh fetch of labels for this MCC scope. Defaults to false (cache-first).
`label_filter`	`array`	Filter by labels. Accepts an array whose entries are any of: label name (e.g. "Big Boom"), bare label ID (e.g. "9876543210"), or full label resource name (e.g. "customers/1234567890/labels/9876543210"). Names are resolved against cached labels for the relevant customer scope. Unknown names return an empty result with a warning rather than an error.

Parameter	Type	Description
`customer_id` required	`string`	The Google Ads customer ID
`ads` required	`array`	Ads to preview (1-20)
`reason` required	`string`	Why this tool call is needed

Parameter	Type	Description
`login_customer_id`	`string`	MCC manager account ID if needed
`metric_labels`	`object`	Display labels for metric keys

Parameter	Type	Description
`reason` required	`string`	Brief explanation of why you are rendering this chart
`chart` required	`object`	Chart configuration. Supported types: bar, scatter, timeseries, funnel, waterfall, choropleth.

Parameter	Type	Description
`feedback_type` required	`string`	Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)
`title` required	`string`	Concise title summarizing the feedback
`description` required	`string`	What is needed and why
`reason` required	`string`	Why this tool call is needed

Parameter	Type	Description
`current_workaround`	`string`	Current workaround, if any
`priority`	`string`	Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)
`interface`	`string`	Interface the feedback originated from: MCP (default) or CLI

Parameter	Type	Description
`entity_type` required	`string`	Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad
`entity_id` required	`string`	The platform entity ID (e.g. act_123456, 23842453456789)
`key` required	`string`	Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)
`reason` required	`string`	Why this tool call is needed

Parameter	Type	Description
`value`	`unknown`	Preference value — string, number, boolean, or JSON object
`source`	`string`	Who set this preference: agent (default), user, or system
`note`	`string`	Optional context about why this preference was set

Parameter	Type	Description
`login_customer_id`	`string`	MCC (Manager) Customer ID; required for managed accounts
`status`	`string`	Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN
`limit`	`number`	Maximum number of conversion actions to return (default: 100, max: 500)
`lookback_days`	`integer`	Lookback window (days) for recent conversion counts. Default 30.
`include`	`array`	Which optional blocks to compute. 'effective' = goal-hierarchy walk (3 extra GAQL queries). 'recent' = metrics.conversions over the lookback window (1 extra query). 'campaign_overrides' = list the contributing campaign IDs per action, grouped by source (HEAVY — full list, no cap; only request when the user explicitly asks 'which campaigns?'). Implies 'effective'. 'tag_snippets' = include tag snippet HTML per row. 'attribution' = include attribution-model + value settings. Default: ['effective','recent']. Pass [] for the lightest possible response.

Parameter	Type	Description
`login_customer_id`	`string`	MCC (Manager) Customer ID; required for managed accounts
`keywords`	`array`	Seed keywords to generate ideas from (max 20). At least one of keywords or url must be provided.
`url`	`string`	Seed URL to generate keyword ideas from. At least one of keywords or url must be provided.
`language`	`string`	ISO 639-1 language code (e.g., "en", "es"). Default: "en".
`geo_targets`	`array`	ISO 3166-1 alpha-2 country codes (e.g., ["US", "GB"]). Default: ["US"].
`network`	`string`	Keyword plan network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS
`include_adult_keywords`	`boolean`	Whether to include adult keyword ideas. Default: false.
`include_monthly_volumes`	`boolean`	When true, includes per-month search volume history for each keyword. Default: false.
`limit`	`integer`	Maximum keyword ideas to return per page (1-1000, default 50)
`cursor`	`string`	Opaque pagination cursor from a previous response. Do not construct manually.

Parameter	Type	Description
`login_customer_id`	`string`	MCC (Manager) Customer ID; required for managed accounts
`language`	`string`	ISO 639-1 language code (e.g. "en", "es"). Maps internally to languageConstants resource name.
`geo_targets`	`array`	ISO 3166-1 alpha-2 country codes (e.g. ["US", "GB"]). Maps internally to geoTargetConstants.
`network`	`string`	Network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS
`include_monthly_volumes`	`boolean`	When true, includes month-by-month search volume data. Default: false.

Parameter	Type	Description
`login_customer_id`	`string`	MCC (Manager) Customer ID; required for managed accounts
`default_max_cpc_bid_micros`	`integer`	Default max CPC bid in micros. Required for MANUAL_CPC strategy. Per-keyword bids override this.
`bidding_strategy`	`string`	Bidding strategy: MANUAL_CPC (default), MAXIMIZE_CLICKS, or MAXIMIZE_CONVERSIONS
`max_cpc_bid_ceiling_micros`	`integer`	Max CPC bid ceiling for MAXIMIZE_CLICKS strategy (micros). Ignored for other strategies.
`geo_targets`	`array`	ISO 3166-1 alpha-2 country codes (e.g., ["US", "GB"]). Default: ["US"].
`language`	`string`	ISO 639-1 language code (e.g., "en", "es"). Default: "en".
`network`	`string`	Ad network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS
`forecast_start_date`	`string`	Forecast period start date (YYYY-MM-DD). Defaults to tomorrow.
`forecast_end_date`	`string`	Forecast period end date (YYYY-MM-DD). Defaults to 30 days from start.
`negative_keywords`	`array`	Negative keyword texts to exclude from the forecast
`conversion_rate`	`number`	Expected conversion rate (0-1, e.g., 0.05 for 5%)
`currency_code`	`string`	ISO 4217 currency code (e.g., "USD", "EUR"). Defaults to account currency.

Installation

Claude Desktop

CLI

Platform Overview

Common Workflows

Performance Reporting

Campaign & Ad Group Management

Keyword & Search Term Analysis

Geographic & Audience Insights

Recipes

Tips

Tools

account-summary

google_ads_get_account_summary Get Google Ads Account Summary

activities

google_ads_get_activities Get Google Ads Activities

accounts

google_ads_list_accounts List Google Ads Accounts

mcc-child-accounts

google_ads_list_mcc_child_accounts List MCC Child Accounts

ad-groups

google_ads_list_ad_groups List Google Ads Ad Groups

ads

google_ads_preview_ads Preview Google AdsMCP App

google_ads_list_ads List Google Ads

audiences

google_ads_list_audiences List Google Ads Audiences

auth

google_ads_check_auth_status Check Google Ads Auth Status

google_ads_ping Ping Google Ads MCP Server

auto-applied-recommendations

google_ads_get_auto_applied_recommendations Check Google Ads Auto-Applied Recommendations

campaigns

google_ads_list_campaigns List Google Ads Campaigns

chart

google_ads_render_chart Render ChartMCP App

conversion-actions

google_ads_get_conversion_actions List Google Ads Conversion Actions

feedback

google_ads_developer_feedback Submit Developer Feedback

geo-performance

google_ads_get_geo_performance Get Google Ads Geographic Performance

insights

google_ads_get_insights Get Google Ads Insights

generate-keyword-ideas

google_ads_generate_keyword_ideas Generate Google Ads Keyword Ideas

keyword-historical-metrics

google_ads_get_keyword_historical_metrics Get Google Ads Keyword Historical Metrics

generate-keyword-forecast-metrics

google_ads_generate_keyword_forecast_metrics Generate Google Ads Keyword Forecast Metrics

generate-ad-group-themes

google_ads_generate_ad_group_themes Generate Google Ads Ad Group Themes

keyword-performance

google_ads_get_keyword_performance Get Google Ads Keyword Performance

search-terms-report

google_ads_get_search_terms_report Get Google Ads Search Terms Report

landing-page-report

google_ads_get_landing_page_report Get Landing Page Performance Report

negative-keyword-lists

google_ads_list_negative_keyword_lists List Google Ads Negative Keyword Lists

negative-keywords

google_ads_list_negative_keywords List Google Ads Negative Keywords

reporting

google_ads_get_performance_report Get Google Ads Performance Report

preferences

google_ads_store_preference Store Google Ads Preference

google_ads_get_preferences Get Google Ads Preferences

google_ads_delete_preference Delete Google Ads Preference

`google_ads_get_account_summary` Get Google Ads Account Summary

`google_ads_get_activities` Get Google Ads Activities

`google_ads_list_accounts` List Google Ads Accounts

`google_ads_list_mcc_child_accounts` List MCC Child Accounts

`google_ads_list_ad_groups` List Google Ads Ad Groups

`google_ads_preview_ads` Preview Google AdsMCP App

`google_ads_list_ads` List Google Ads

`google_ads_list_audiences` List Google Ads Audiences

`google_ads_check_auth_status` Check Google Ads Auth Status

`google_ads_ping` Ping Google Ads MCP Server

`google_ads_get_auto_applied_recommendations` Check Google Ads Auto-Applied Recommendations

`google_ads_list_campaigns` List Google Ads Campaigns

`google_ads_render_chart` Render ChartMCP App

`google_ads_get_conversion_actions` List Google Ads Conversion Actions

`google_ads_developer_feedback` Submit Developer Feedback

`google_ads_get_geo_performance` Get Google Ads Geographic Performance

`google_ads_get_insights` Get Google Ads Insights

`google_ads_generate_keyword_ideas` Generate Google Ads Keyword Ideas

`google_ads_get_keyword_historical_metrics` Get Google Ads Keyword Historical Metrics

`google_ads_generate_keyword_forecast_metrics` Generate Google Ads Keyword Forecast Metrics

`google_ads_generate_ad_group_themes` Generate Google Ads Ad Group Themes

`google_ads_get_keyword_performance` Get Google Ads Keyword Performance

`google_ads_get_search_terms_report` Get Google Ads Search Terms Report

`google_ads_get_landing_page_report` Get Landing Page Performance Report

`google_ads_list_negative_keyword_lists` List Google Ads Negative Keyword Lists

`google_ads_list_negative_keywords` List Google Ads Negative Keywords

`google_ads_get_performance_report` Get Google Ads Performance Report

`google_ads_store_preference` Store Google Ads Preference

`google_ads_get_preferences` Get Google Ads Preferences

`google_ads_delete_preference` Delete Google Ads Preference