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 Meta ad account (every write tool call made via gadspilot, with parameters + result, dry-runs included). Persistent across sessions. Call this BEFORE making changes to know what was already done.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Optional when only one Meta account is authorized. |
date_range
|
string | Default: last_30_days. |
tool_name
|
string | Optional filter — exact tool name (e.g. meta_update_campaign_status). |
campaign_id
|
string | Optional filter — only changes whose parameters reference this campaign_id. |
include_dry_run
|
boolean | Default: true. Set false to exclude previewed-only operations. |
get_notes
Read
Returns persistent notes attached to this Meta ad account (level "property") or to one campaign_id inside it (level "target"). Call this BEFORE analysis or changes to recover previous context.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Optional when only one Meta account is authorized. |
campaign_id
|
string | Optional — only notes attached to this campaign_id. |
tags
|
array | Optional — only notes matching at least one of these tags. |
add_note
Read
Persists a free-text note on this Meta ad account. Pass campaign_id when the note is about one specific campaign_id; omit it for Meta ad account-wide notes. Use it to record WHY a change was made, hypotheses, or what to re-check later.
Parameters
act_id
|
string | Meta ad account id (with or without "act_" prefix). Optional when only one Meta account is authorized. |
campaign_id
|
string | Optional — attach the note to this specific campaign_id. Omit for Meta ad account-wide notes. |
note
*
|
string | The note content. Be specific: include numbers, dates, hypotheses, re-check date. |
tags
|
array | Optional tags (e.g. ["experiment", "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
