Documentation
Connect your marketing data to Claude, ChatGPT and other LLMs.
MCP Tools — Meta Ads
14 tools exposed on the https://gadspilot.com/mcp-meta 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 (5)
meta_campaign_insights
Read
Campaign-level insights (spend, impressions, clicks, CTR, CPM, ROAS). Uses Meta date preset or since/until.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
date_preset
|
string | Meta date preset. Ignored if since/until provided. |
since
|
string | ISO date YYYY-MM-DD (requires until) |
until
|
string | ISO date YYYY-MM-DD |
campaign_id
|
string |
meta_adset_insights
Read
Ad set-level insights. Filterable by campaign_id.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
date_preset
|
string | Meta date preset. Ignored if since/until provided. |
since
|
string | |
until
|
string | |
campaign_id
|
string |
meta_ad_insights
Read
Ad-level insights (creative performance). Filterable by campaign_id / adset_id.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
date_preset
|
string | Meta date preset. Ignored if since/until provided. |
since
|
string | |
until
|
string | |
campaign_id
|
string | |
adset_id
|
string |
meta_breakdown_report
Read
Insights segmented by breakdown (age, gender, country, publisher_platform, platform_position, device_platform, impression_device).
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
level
|
string | Granularity of the report. |
breakdowns
*
|
string | Comma-separated breakdowns, e.g. "age,gender" or "publisher_platform,platform_position". |
date_preset
|
string | Meta date preset. Ignored if since/until provided. |
since
|
string | |
until
|
string | |
campaign_id
|
string |
meta_account_summary
Read
Top-level KPIs for a Meta ad account (aggregated spend, clicks, CPM, CTR, ROAS).
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
date_preset
|
string | Meta date preset. Ignored if since/until provided. |
since
|
string | |
until
|
string |
🏗 Structure & Listing (2)
meta_list_ad_accounts
Read
List all Meta ad accounts accessible with this token.
Parameters
meta_list_campaigns
Read
List Meta Ads campaigns with status, objective, budget.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
status
|
string |
✏️ Write actions (4)
All default to dry-run mode
meta_update_campaign_status
Write · dry-run
Pause or activate a Meta campaign. WRITE — dry_run=true by default.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
campaign_id
*
|
string | |
status
*
|
string | |
dry_run
|
boolean |
meta_update_campaign_budget
Write · dry-run
Update daily or lifetime budget of a Meta campaign (values en cents — 1000 = 10,00 devise compte). WRITE.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
campaign_id
*
|
string | |
daily_budget_cents
|
integer | |
lifetime_budget_cents
|
integer | |
dry_run
|
boolean |
meta_update_adset_budget
Write · dry-run
Update daily or lifetime budget of a Meta ad set (en cents). WRITE.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
adset_id
*
|
string | |
daily_budget_cents
|
integer | |
lifetime_budget_cents
|
integer | |
dry_run
|
boolean |
meta_pause_ad
Write · dry-run
Pause a specific Meta ad. WRITE.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Required when multiple Meta accounts are authorized. |
ad_id
*
|
string | |
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\"]). |
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