Google Ads MCP

Audit trail: who changed what in the last 30 days. Max window is 30 days back. Returns: change_date_time, user_email, change_resource_type (CAMPAIGN|AD_GROUP|AD_GROUP_CRITERION|CAMPAIGN_BUDGET| AD|AD_GROUP_BID_MODIFIER|…), old_resource, new_resource, changed_fields, client_type (GOOGLE_ADS_WEB_CLIENT|GOOGLE_ADS_API|…). Args: customer_id: 10-digit customer_id. days_back: 1–30. resource_types: optional filter to specific change_resource_type enum values. limit: max rows (default 10000, capped 100000).

Lightweight change tracker: last-modified-at timestamps for resources. Unlike change_event, this is a per-resource "last modified" view rather than a change-diff log. Covers up to 14 days. Args: customer_id: 10-digit customer_id. days_back: 1–14. resource_types: optional filter by change_status.resource_type enum. limit: max rows.

Schema (fields, metrics, segments) for a GAQL resource. Queries GoogleAdsFieldService for every selectable field on a resource plus its data type, selectability, filterability, sort-ability, and `selectable_with` (which other fields can coexist in a single SELECT). Args: resource_name: the GAQL resource, e.g. "campaign", "ad_group", "shopping_performance_view", "change_event", "recommendation". Returns: {resource, fields: [{name, category: ATTRIBUTE|METRIC|SEGMENT, data_type, selectable, filterable, sortable, enum_values, type_url, selectable_with}]}. Essential before composing GAQL on an unfamiliar resource; prevents FIELD_NOT_COMPATIBLE and FIELD_NOT_FOUND errors.

Forecast KPIs (impressions, clicks, cost, conversions) for a proposed keyword plan. Args: customer_id: 10-digit customer_id. campaign_spec: a KeywordPlanCampaign forecast spec. Minimum shape: { "bidding_strategy": "MANUAL_CPC", "daily_budget_micros": 10000000, "keyword_match_type": "BROAD" | "PHRASE" | "EXACT", "language_id": "1000", "geo_target_ids": ["2840"], "keywords": ["running shoes", "trail running shoes"] } Returns: {campaign_forecast: {impressions, clicks, cost_micros, conversions, average_cpc_micros}, weekly_time_series: [...]}. Rate limit: 1 QPS. Requires Basic Access.

Historical monthly search-volume + competition metrics for specific keywords. Args: customer_id: 10-digit customer_id. keywords: list of keyword strings (max 10,000 per call). language_id / geo_target_ids / keyword_network: same shape as keyword_ideas. year_month_start / year_month_end: optional date range as {year: 2025, month: 1..12}. Defaults to last 12 months. Returns: {results: [{text, approximate_monthly_searches, monthly_search_volumes: [{year, month, monthly_searches}], competition, high/low_top_of_page_bid_micros}]}. Rate limit: 1 QPS. May require Basic Access.

Generate keyword ideas with search volume + competition + CPC estimates. Args: customer_id: customer_id to attribute the request (any Ads account under MCC works). keywords: seed keywords, list of strings. Optional if page_url is given. page_url: seed URL (crawled for keyword extraction). Optional if keywords given. language_id: Google language criterion ID. Default '1000' (English). Common: '1001' Spanish, '1002' French, '1003' German, '1007' Italian. geo_target_ids: list of geo criterion IDs. Default ['2840'] (US). Common: '2826' UK, '2124' Canada, '2036' Australia, '2276' Germany. keyword_network: GOOGLE_SEARCH (default) | GOOGLE_SEARCH_AND_PARTNERS. include_adult: include adult-category keywords (default False). page_size: max ideas to return (default 100, capped at 10000). Returns: {ideas: [{text, avg_monthly_searches, competition, low_top_of_page_bid_micros, high_top_of_page_bid_micros, concept_group}]}. Rate limit: 1 QPS for this service. Back off on RESOURCE_EXHAUSTED. Requires Basic Access (Explorer may 403); if you get USER_PERMISSION_DENIED, the dev_token tier is too low.

List every customer_id the OAuth user has direct access to. This is a small, cheap list, typically just the MCC itself and any standalone accounts. For the full tree of accounts under the MCC (agency use case), call google_ads_list_customer_clients instead. Returns: {"resource_names": [...], "customer_ids": [...]}. Each customer_id is 10 digits, no hyphens.

Walk the MCC (Manager Account) hierarchy and return every child account. For agency use: this is the canonical "which clients can I query?" call. Uses GAQL on the `customer_client` resource. Fast: one streaming call. Args: mcc_customer_id: MCC customer_id. Defaults to GOOGLE_ADS_LOGIN_CUSTOMER_ID (the configured MCC). Accepts 10-digit or hyphenated. include_managers: include sub-MCCs in the result (default True). include_hidden: include customer_clients marked hidden=True (default False). max_level: max hierarchy depth (default 3, hard cap 10). Returns per account: customer_id, descriptive_name, currency_code, time_zone, manager (bool), level, status (ENABLED|CANCELED|…), hidden, resource_name.

Return the full catalog of GAQL resources (FROM-able tables). Useful when the agent needs to pick the right resource for a question. Each entry: name, category, selectable (whether it can be the FROM target). Response is cacheable for the session; the catalog is stable across queries.

Run a GAQL (Google Ads Query Language) query against a specific customer account. GAQL is SQL-like: `SELECT ... FROM <single_resource> WHERE ... ORDER BY ... LIMIT ...`. No JOINs; attribute fields from related resources by selecting them directly. Common resources: campaign, ad_group, keyword_view, search_term_view, shopping_performance_view, customer, customer_client, conversion_action, change_event, change_status, recommendation, asset, asset_group. Use google_ads_describe_resource first if unsure of field names on a new resource; saves a FIELD_NOT_FOUND roundtrip. Args: customer_id: 10-digit customer_id (no hyphens) for the account to query. gaql: the full GAQL query string (must start with SELECT; no semicolons). max_rows: if set, stop streaming after this many rows. Defaults to unbounded (the 64 MB response cap still applies). convert_micros: if True (default), also emit <metric>_units alongside any <metric>_micros field (divided by 1,000,000). E.g. cost_micros = 12345678 → cost_units = 12.345678. Example queries: SELECT campaign.id, campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50 SELECT ad_group.name, ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks FROM keyword_view WHERE segments.date DURING LAST_30_DAYS SELECT segments.product_item_id, metrics.conversions_value FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS Gotchas (surface to user where relevant): - metrics.cost_micros: 1 unit = $0.000001. Divide by 1M for currency. - LAST_30_DAYS = 30 days ending YESTERDAY (today excluded). - Last 72h data is partial; conversions retroactively re-attribute. - Zero-metric rows are excluded when segmenting by date. - Response cap is 64 MB per call; split by date range for huge reports. - GAQL `IN (...)` clause is capped at 20,000 items.

Read Google's optimization recommendations for a customer account. Returns suggestions only; does NOT apply any. Types include: KEYWORD, CAMPAIGN_BUDGET, KEYWORD_MATCH_TYPE, TARGET_CPA_OPT_IN, MAXIMIZE_CLICKS_OPT_IN, OPTIMIZE_AD_ROTATION, RESPONSIVE_SEARCH_AD, ENHANCED_CPC_OPT_IN, SEARCH_PARTNERS_OPT_IN, SITELINK_EXTENSION, CALL_EXTENSION, CALLOUT_EXTENSION, STRUCTURED_SNIPPET_EXTENSION, DISPLAY_EXPANSION_OPT_IN, KEYWORD_MATCH_TYPE, FORECASTING_*, SHOPPING_*, MOVE_UNUSED_BUDGET. (Google adds new types over time.) Args: customer_id: 10-digit account ID. types: optional list to filter by recommendation_type. Case-sensitive. dismissed: include dismissed recommendations (default False). limit: max rows (default 200). Each row contains: type, impact (absolute_metrics, base_metrics, potential_metrics), campaign / ad_group ref (if applicable), dismissed flag, recommendation-specific payload (e.g. suggested_keywords, budget_increase).