Documentation
Connect your marketing data to Claude, ChatGPT and other LLMs.
MCP Tools — Google Ads
41 tools exposed on the https://gadspilot.com/mcp endpoint. Click a tool to see its parameters.
💡
You never need to call these tools manually — ask your question in plain English to Claude/ChatGPT/Cursor, the LLM picks the right tool, handles the parameters and summarizes the response. This doc just lists what's available.
📊 Reporting & Insights (17)
get_campaign_performance
Read
Campaign metrics for a date range.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_ad_group_performance
Read
Ad group level metrics.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_keyword_performance
Read
Keywords with quality score + metrics. Each keyword is annotated with effectively_blocked_by[] listing campaign/ad-group negatives that would block search queries matching it (and is_blocked boolean). Set include_negative_check=false to skip this aggregation.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string | |
ad_group_id
|
string | |
min_impressions
|
integer | |
include_negative_check
|
boolean | Default true. Set false to skip the negative cross-check (faster). |
get_search_terms
Read
Actual search queries triggering ads, cross-referenced with configured keywords.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string | |
ad_group_id
|
string | |
min_cost_micros
|
integer | |
sort_by
|
string |
get_ad_performance
Read
RSA ad performance with ad strength and assets.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_geographic_report
Read
Performance by country, region, or city. Returns geographic_view.country_criterion_id (numeric Google geo ID).
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string | |
ad_group_id
|
string | |
level
|
string |
get_device_report
Read
Performance split by device (MOBILE, DESKTOP, TABLET).
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_hourly_report
Read
Performance by hour of day and/or day of week.
Parameters
date_range
*
|
string | Date range shortcut. |
segment_by
|
string | |
campaign_id
|
string |
get_auction_insights
Read
Impression share vs competitors.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_budget_pacing
Read
Daily budget vs actual spend with pacing analysis.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_change_history
Read
All account changes with before/after values.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string | |
resource_type
|
string |
get_pmax_performance
Read
Performance Max campaign details.
Parameters
date_range
*
|
string | Date range shortcut. |
campaign_id
|
string |
get_recommendations
Read
Google native optimization recommendations.
Parameters
get_responsive_search_ads
Read
List Responsive Search Ads with headlines, descriptions, paths, final URLs and ad strength. Filterable by campaign / ad group / status.
Parameters
campaign_id
|
string | |
ad_group_id
|
string | |
status
|
string |
get_account_summary
Read
Top-level account KPIs for a date range.
Parameters
date_range
*
|
string | Date range shortcut. |
get_account_budget_summary
Read
All campaign budgets with spend and pacing.
Parameters
date_range
*
|
string | Date range shortcut. |
🏗 Structure & Listing (5)
list_accounts
Read
List all Google Ads accounts accessible with this token.
Parameters
list_campaigns
Read
List all campaigns with status and basic config.
Parameters
status
|
string | |
type
|
string |
list_negative_keywords
Read
List all negative keywords (campaign-level and ad-group-level) for the account or for a specific campaign/ad group. Returns separate arrays for campaign_negatives and ad_group_negatives with text + match_type.
Parameters
campaign_id
|
string | |
ad_group_id
|
string |
list_conversion_actions
Read
List all conversion actions with their status, type, category, primary_for_goal flag, value settings, and attribution model. Essential for audit start.
Parameters
status
|
string |
list_campaign_locations
Read
List all LOCATION criteria of campaign(s) — geographic targeting (countries, regions, cities), with negative flag and bid_modifier. Use this before any geo write operation.
Parameters
campaign_id
|
string |
✏️ Write actions (14)
All default to dry-run mode
create_search_campaign
Write · dry-run
Create a Search campaign.
Parameters
name
*
|
string | |
daily_budget_micros
*
|
integer | |
bidding_strategy
*
|
string | |
target_cpa_micros
|
integer | |
target_roas
|
number | |
geo_target_ids
|
array | |
language_ids
|
array | |
dry_run
|
boolean |
create_ad_group
Write · dry-run
Create an ad group inside an existing campaign.
Parameters
campaign_id
*
|
string | |
name
*
|
string | |
cpc_bid_micros
|
integer | |
dry_run
|
boolean |
create_rsa_ad
Write · dry-run
Create a Responsive Search Ad. Headlines & descriptions accept either a plain string or an object {text, pinnedField} where pinnedField is HEADLINE_1/2/3 (headlines) or DESCRIPTION_1/2 (descriptions). Optional final_url_suffix and url_custom_parameters [{key, value}] for tracking.
Parameters
ad_group_id
*
|
string | |
headlines
*
|
array | 3 to 15 headlines, max 30 chars each. Each item is either a plain string or {text, pinnedField}. |
descriptions
*
|
array | 2 to 4 descriptions, max 90 chars each. Each item is either a plain string or {text, pinnedField}. |
final_url
*
|
string | Landing page URL (https://…). |
path1
|
string | Display URL path 1 (max 15 chars). |
path2
|
string | Display URL path 2 (max 15 chars). |
final_url_suffix
|
string | Tracking suffix appended to the final URL (e.g. "cpurl={_cpurl}"). |
url_custom_parameters
|
array | Custom URL parameters used by ValueTrack {_xxx} tokens. |
dry_run
|
boolean |
add_keywords
Write · dry-run
Add keywords to an ad group.
Parameters
ad_group_id
*
|
string | |
keywords
*
|
array | |
dry_run
|
boolean |
add_negative_keywords
Write · dry-run
Add negative keywords at campaign or ad group level.
Parameters
level
*
|
string | |
campaign_id
*
|
string | |
ad_group_id
|
string | |
keywords
*
|
array | |
dry_run
|
boolean |
update_campaign_budget
Write · dry-run
Change a campaign's daily budget.
Parameters
campaign_id
*
|
string | |
new_budget_micros
*
|
integer | |
dry_run
|
boolean |
update_campaign_status
Write · dry-run
Enable or pause a campaign.
Parameters
campaign_id
*
|
string | |
status
*
|
string | |
dry_run
|
boolean |
update_bidding_strategy
Write · dry-run
Change campaign bidding strategy.
Parameters
campaign_id
*
|
string | |
bidding_strategy
*
|
string | |
target_cpa_micros
|
integer | |
target_roas
|
number | |
dry_run
|
boolean |
pause_ad
Write · dry-run
Pause a specific ad.
Parameters
ad_group_ad_id
*
|
string | Format: ad_group_id~ad_id |
dry_run
|
boolean |
remove_ad
Write · dry-run
Permanently remove (soft-delete) a specific ad. Sets the ad status to REMOVED — Google Ads has no DELETE operation for ads. This is IRREVERSIBLE: the ad cannot be re-enabled, only re-created from scratch. Use pause_ad if you may want to re-enable later.
Parameters
ad_group_ad_id
*
|
string | Format: ad_group_id~ad_id (e.g. 10719290410~806542107985) |
dry_run
|
boolean |
add_negative_locations
Write · dry-run
Exclude N countries/regions from a campaign in one call. country_criterion_ids are Google geo target constants (e.g. 2250=France, 2384=Côte d'Ivoire, 2466=Mali). Get IDs from https://developers.google.com/google-ads/api/reference/data/geotargets. Detects automatically if a country is already targeted POSITIVELY on this campaign (Google Ads forbids same location being both positive and negative): without `replace_existing` returns a structured CONFLICT_POSITIVE_EXISTS error listing the criterion_ids; with `replace_existing=true` removes the positive criteria and creates the negative ones in a single atomic batch.
Parameters
campaign_id
*
|
string | |
country_criterion_ids
*
|
array | Array of Google geo target constant IDs to exclude. |
replace_existing
|
boolean | Default false. If true, automatically removes any existing POSITIVE criterion on these countries before creating the negative ones (atomic). Use when the user explicitly wants to flip a country from positive targeting to exclusion. |
dry_run
|
boolean |
set_location_bid_modifier
Write · dry-run
Set bid modifier for a single country/region on a campaign. bid_modifier 1.0=no change, 1.30=+30%, 0.80=-20%, 0.50=-50%. Range: 0.1 to 10.0. If criterion already exists it is updated, otherwise created.
Parameters
campaign_id
*
|
string | |
country_criterion_id
*
|
integer | Google geo target constant ID. |
bid_modifier
*
|
number | |
dry_run
|
boolean |
set_location_bid_modifiers_batch
Write · dry-run
Apply multiple location bid modifiers in one call. modifiers is an object {country_criterion_id: bid_modifier}.
Parameters
campaign_id
*
|
string | |
modifiers
*
|
object | Object mapping country_criterion_id (string key) to bid_modifier (number). |
dry_run
|
boolean |
remove_location_criterion
Write · dry-run
Remove a location criterion (negative or positive) from a campaign. criterion_id is the campaign_criterion criterion_id (NOT the geo target id) — get it from list_campaign_locations first.
Parameters
campaign_id
*
|
string | |
criterion_id
*
|
integer | campaign_criterion.criterion_id from list_campaign_locations. |
dry_run
|
boolean |
🧠 Persistent memory (3)
Notes + change log shared across sessions
get_local_change_log
Read
Returns gadspilot's own write history for this account (every write tool call ever made via gadspilot, with parameters + result). Persistent across sessions. Use this BEFORE making changes to know what was already done previously. Different from get_change_history which only shows changes done via Google Ads UI/API.
Parameters
date_range
|
string | Default: last_30_days. |
tool_name
|
string | Optional filter — exact tool name (e.g. update_campaign_budget). |
campaign_id
|
string | Optional filter — only changes that touched this campaign. |
include_dry_run
|
boolean | Default: true. Set false to exclude previewed-only operations. |
get_notes
Read
Returns persistent notes attached to campaigns OR ad groups. Each note has a `level` field ("campaign" or "ad_group"). When recovering context for an ad group, ALWAYS pull both campaign-level (ad_group_id NULL) and ad-group-level notes — campaign context applies to all its ad groups.
Parameters
campaign_id
|
string | Optional — only notes for this campaign. |
ad_group_id
|
string | Optional — only notes for this specific ad group. |
scope
|
string | Default "all". Use "campaign_only" to get notes attached at campaign level (ad_group_id NULL), "ad_group_only" for notes attached to any ad group of the campaign. |
tags
|
array | Optional — only notes matching at least one of these tags. |
add_note
Read
Persists a free-text note. Attach at the MOST SPECIFIC level applicable: if the change/observation is about ONE ad group (bid, keywords inside, ads, RSA themes), pass ad_group_id. If it spans the whole campaign (budget, geo, bidding strategy, multi-AG insight), omit ad_group_id and only pass campaign_id. Use this to record WHY a change was made, hypotheses, or what to re-check later.
Parameters
campaign_id
*
|
string | |
ad_group_id
|
string | OPTIONAL but RECOMMENDED when the note is specific to one ad group. Omit only for campaign-wide notes. |
note
*
|
string | The note content. Be specific: include numbers, dates, hypotheses, re-check date. |
tags
|
array | Optional tags to organize notes (e.g. [\"experiment\", \"bid-test\", \"to-review\"]). |
🔧 Power tools (2)
generate_keyword_ideas
Read
Keyword research using Google Keyword Planner.
Parameters
keywords
*
|
array | |
language_id
|
string | |
geo_target_ids
|
array |
execute_gaql
Read
Run an arbitrary GAQL SELECT query.
Parameters
query
*
|
string |
General conventions
- READ tools: no risk, real-time read-only via Google Ads API / GSC API / Meta Marketing API
- WRITE tools: default
dry_run=true→ returns a JSON preview without modifying anything. You must explicitly passdry_run=falseto execute (and you can disable writes globally per account in gadspilot) - Memory tools: lightweight write to gadspilot DB only (notes/change log) — does not call Google/Meta APIs, no dry-run needed
- All monetary values are in micros on Google Ads (€1 = 1,000,000 micros). gadspilot automatically converts responses
- All writes are logged in /logs with params + result + dry-run flag