Skip to main content
Glama
chatgpt-ads-manager-mcp

chatgpt-ads-manager-mcp

by niyogi

ChatGPT Ads Manager MCP

npm version npm downloads License: MIT

Manage your ChatGPT Advertiser campaigns from any MCP-capable agent — Claude Desktop, Cursor, VS Code (Copilot), Windsurf, and more.

One npx command. No app to install. Your API key stays local on your machine.

Published to npm — npx -y chatgpt-ads-manager-mcp pulls the pre-built package from npmjs.com/package/chatgpt-ads-manager-mcp on demand. No git clone, no npm run build — just paste a config and restart your agent.

  • Create campaigns → ad groups → ads (or all three in one chain)

  • Upload creatives, manage audiences, configure conversions & pixels

  • Pull insights at account / campaign / ad group / ad level

  • Business Agents & Lead Forms, product feeds, geo targeting — everything in the Advertiser API

Built for agents that chain tools. Every create_* returns the ID you need for the next call.


1. Get your API key

  1. Open Ads Manager → Settings → API Keys at ads.openai.com.

  2. Create a key (scoped to one ad account) and copy it. It looks like sk-ads-....

Keep it secret — you'll paste it into your MCP config, never into chat.


Related MCP server: OpenAI Ads & Conversion Intelligence MCP Server

2. Add to your agent (copy-paste)

You need Node.js >= 18. Check with node -v.

All configs below use the env var OPENAI_ADS_API_KEY (alias CHATGPT_ADS_API_KEY also works). For multi-account / partner setups, also set OPENAI_AD_ACCOUNT_ID or pass ad_account_id per tool call — see §7.

Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chatgpt-ads-manager": {
      "command": "npx",
      "args": ["-y", "chatgpt-ads-manager-mcp@latest"],
      "env": {
        "OPENAI_ADS_API_KEY": "sk-ads-...paste-your-key..."
      }
    }
  }
}

Tip: @latest auto-updates on next agent restart. Pin to a version for reproducibility: ["-y", "chatgpt-ads-manager-mcp@0.1.0"]. Bare chatgpt-ads-manager-mcp also resolves to @latest.

Restart Claude Desktop.

Cursor

Global (~/.cursor/mcp.json — all projects) or project-scoped (.cursor/mcp.json — commit without secrets):

{
  "mcpServers": {
    "chatgpt-ads-manager": {
      "command": "npx",
      "args": ["-y", "chatgpt-ads-manager-mcp@latest"],
      "env": {
        "OPENAI_ADS_API_KEY": "sk-ads-...paste-your-key..."
      }
    }
  }
}

Settings → Tools & MCP will hot-reload — no restart needed.

VS Code (Copilot / MCP extension)

Create .vscode/mcp.json in your workspace (note servers + type: "stdio" — VS Code's variant):

{
  "servers": {
    "chatgpt-ads-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "chatgpt-ads-manager-mcp@latest"],
      "env": {
        "OPENAI_ADS_API_KEY": "sk-ads-...paste-your-key..."
      }
    }
  }
}

Claude Code (CLI)

claude mcp add chatgpt-ads-manager -- npx -y chatgpt-ads-manager-mcp@latest
# then in your config add env:
# OPENAI_ADS_API_KEY=sk-ads-...
# or: claude mcp add --env OPENAI_ADS_API_KEY=sk-ads-... chatgpt-ads-manager -- npx -y chatgpt-ads-manager-mcp@latest

Scope it: --scope project for the repo, --scope user for global.

Windsurf / Cline / Continue / any mcp.json client

{
  "mcpServers": {
    "chatgpt-ads-manager": {
      "command": "npx",
      "args": ["-y", "chatgpt-ads-manager-mcp@latest"],
      "env": {
        "OPENAI_ADS_API_KEY": "sk-ads-...paste-your-key..."
      }
    }
  }
}

All examples now use @latest so npx fetches the newest published version from npm on next restart. Replace with @0.1.0 to lock.

Remote/HTTP clients: this package is stdio via npx today (no hosted URL). Wrap with mcp-remote if you need HTTP.


3. Verify it works

Ask your agent:

"Verify my ChatGPT Ads connection with get_ad_account, then list my campaigns."

What you should see:

  • get_ad_account → { id: "adacct_...", name: "…", status: "active", timezone, currency_code }

  • list_campaigns → { data: [...] } with campaign_ids for next steps

If get_ad_account says 401, your key is wrong/expired — create a new one in Ads Manager. 403 means the account isn't enabled for that resource (e.g., conversions or brand updates need partner enablement).


4. What you can do — example prompts

Copy these verbatim to your agent. They show the elegant chaining this MCP is designed for.

  1. End-to-end in one call

    "Create a paused campaign called 'Fall Launch' with $50/day budget, then an ad group 'Prospecting' with impression bidding, then a chat_card ad titled 'Try Fall Launch' for ad group. Use create_campaign_hierarchy."

  2. Step-by-step (fine-grained)

    "Create a campaign 'Fall Launch' paused with daily_spend_limit_micros 50000000. Then create an ad group for that campaign named 'Prospecting' with billing_event_type impression. Then upload this image https://example.com/creative.png via upload_image and create a chat_card ad in that ad group with title 'Fall is here'."

  3. Geo-targeted campaign

    "Search geo for 'California' with search_geo_lookup, then create a campaign targeting those location IDs."

  4. Creative QA

    "List my ads, pick the most recent, and create_ad_preview for it so I can QA the iframe."

  5. Insights & reporting

    "Get last 30 days daily insights for this account with get_ad_account_insights, then breakdown by country. Also pull conversion insights via get_conversion_insights grouped by campaign."

  6. Audiences

    "Upload a CSV via upload_audience_file then create a custom audience from it, check get_custom_audience until it's ready, and show me targeting ids to use in a campaign."

  7. Conversions setup

    "Create a conversion pixel named 'Checkout' via create_conversion_pixel, then create a conversion API key, then create a conversion event setting for order_created linked to that pixel."

  8. Lead flow

    "Create a lead form with 3 required text fields, publish it, create a business agent that uses it, preview the agent, then publish the agent."

  9. Product catalog

    "List product feeds, query products matching brand='Acme', then patch availability for out-of-stock items."

  10. Spend control

    "Show spend limit windows, then create a new $10k cap for next month."


5. All tools (89)

Every tool accepts optional ad_account_id to override the env default (for multi-account agents). IDs flow forward: campaign_id → ad_group_id → ad_id, file_id → creative, custom_audience_id → targeting.

Ad Account (12)

get_ad_account, list_ad_accounts, update_ad_account_brand, update_ad_account_negative_keywords, activate_ad_account, pause_ad_account, get_ad_account_spend_limit_windows, create_ad_account_spend_limit_window, update_ad_account_spend_limit_window, delete_ad_account_spend_limit_window, get_oauth_me, create_api_key

Campaigns (7)

list_campaigns, get_campaign, create_campaign, update_campaign, activate_campaign, pause_campaign, archive_campaign

Ad Groups (7)

list_ad_groups, get_ad_group, create_ad_group, update_ad_group, activate_ad_group, pause_ad_group, archive_ad_group

Ads (8)

list_ads, get_ad, create_ad, update_ad, create_ad_preview, activate_ad, pause_ad, archive_ad

Insights (5)

get_ad_account_insights, get_campaign_insights, get_ad_group_insights, get_ad_insights, get_conversion_insights

Files / Assets (2)

upload_image (image_url https OR image_base64), upload_audience_file (CSV/TXT base64 → file_id)

Custom Audiences (9)

list_custom_audiences, create_custom_audience, get_custom_audience, archive_custom_audience, add_audience_members, remove_audience_members, replace_audience_members, merge_custom_audiences, get_audience_operation

Business Agents (7)

list_business_agent_tools, list_business_agents, create_business_agent, get_business_agent, update_business_agent, preview_business_agent, publish_business_agent

Lead Forms (7)

list_lead_forms, create_lead_form, get_lead_form, update_lead_form, publish_lead_form, archive_lead_form, create_test_lead_submission

Lead Sync (4)

create_lead_sync_subscription, list_lead_sync_subscriptions, get_lead_sync_subscription, delete_lead_sync_subscription

Conversions Setup (6)

create_conversion_pixel, list_conversion_pixels, create_conversion_api_key, create_conversion_event_setting, list_conversion_event_settings, list_conversion_events

Product Feeds (10)

create_product_feed, list_product_feeds, archive_product_feed, list_product_feed_uploads, query_product_feed_products, patch_product_feed_products, get_product_feed_sftp_access, create_product_feed_sftp_access, activate_product_feed_sftp_access, pause_product_feed_sftp_access

Geo & Partner (3)

search_geo_lookup, create_partner_data_upload, get_partner_data_upload

Workflows (2)

create_campaign_hierarchy (campaign → ad_group → ad in one chained call), poll_audience_operation (check audience mutation status; call repeatedly with backoff)

Coming in v2: Bulk mutation jobs (/bulk_mutation_jobs) and server-side conversions event ingestion to bzr.openai.com (create pixel → send events end-to-end).


6. How chaining works

The MCP is built so an agent never has to guess IDs.

  1. Discover → list_campaigns, list_ad_groups, list_ads, search_geo_lookup, list_custom_audiences

  2. Create → create_campaign returns campaign_id; feed it to create_ad_group → returns ad_group_id → feed to create_ad

  3. Activate → activate_campaign / activate_ad_group / activate_ad (all must be active + ad review_status: approved to serve)

  4. Measure → get_*_insights / get_conversion_insights with time_ranges, segments (product, country, device), fields

  5. Paginate → every list_* + get_*_insights supports limit / after / before / order. Use has_more + first_id / last_id from the response for the next page. Never invent a cursor — use the one returned.

Tip: create_campaign_hierarchy bundles steps 2–3 when you want speed; use atomic create_* tools when you need per-resource control (different bidding configs, product_sets, etc.).


7. Multi-account & env options

Env var

Purpose

Default

OPENAI_ADS_API_KEY

Advertiser API key (primary)

— (required)

CHATGPT_ADS_API_KEY

Alias fallback

—

OPENAI_AD_ACCOUNT_ID

Default ad account for OpenAI-Ad-Account header

—

OPENAI_ADS_BASE_URL

Override API base (e.g., local mock)

https://api.ads.openai.com/v1

  • If both OPENAI_ADS_API_KEY and CHATGPT_ADS_API_KEY are set, OPENAI_... wins.

  • Per-call ad_account_id param wins over the env — use it for partner/agency flows that juggle many accounts.

  • OAuth/shared keys require ad_account_id or OPENAI_AD_ACCOUNT_ID per request; advertiser keys can omit it (header must match the key's account if set).


8. Troubleshooting

  • 401 Ads API ... failed: 401 → key missing/invalid/expired. Regenerate at Ads Manager > Settings > API Keys, then restart your agent.

  • 403 → operation not enabled for this ad account (common for conversions, brand updates, business agents). Contact your OpenAI partner representative.

  • 429 Rate limited. Retry-After: ... → backs off automatically. The API enforces 600 req/min per endpoint and 1200 overall. Wait for Retry-After then retry.

  • Tool "Missing Advertiser API key" → you set the key in the wrong config file or forgot to restart. Copy the exact env block from §2; keep JSON valid (no trailing commas).

  • Upload stuck / audience processing → get_custom_audience / get_audience_operation are async. Poll with backoff; get_partner_data_upload similarly.

  • custom_audience_operation_recovery_required (409) → resend the same body + same idempotency_key.

  • review_status: pending after create_ad → normal; reviews take minutes. Monitor with get_ad.

  • Still stuck? Open an issue: https://github.com/anomalyco/chatgpt-ads-manager-mcp/issues with the tool name + error text (never paste your full key).


9. Security & privacy

  • Your API key never leaves your machine — the MCP fetch calls api.ads.openai.com directly from your local npx process. No proxy, no telemetry.

  • Never log/commit your key. If you use project-scoped .cursor/mcp.json, use ${OPENAI_ADS_API_KEY} placeholder in git and keep the real key in your global ~/.cursor/mcp.json.

  • SSRF-guarded: image_url / target_url / url params are checked for https: only, block private hosts (localhost, 10/8, 192.168/16, 172.16/12, 169.254/16, fc00::/7), block file:/javascript:/data: schemes, cap length, and enforce timeouts. Private-app data can't be exfiltrated via a crafted URL.

  • No exec or shell — file uploads are base64-encoded and sent as multipart FormData; no shell interpolation.

  • Rate-limit aware — respects Retry-After instead of hammering the API.

  • PII-safe: all upstream data is returned as JSON data, never as injected instructions. The MCP doesn't interpret page content as commands.

Report a security issue: please open a private issue or contact the maintainer — don't publish keys in bug reports.


10. Developing / contributing

This section is for contributors only — you don't need it to use the MCP.

git clone https://github.com/anomalyco/chatgpt-ads-manager-mcp
cd chatgpt-ads-manager-mcp
npm install
npm run build        # tsc -> dist/
npm run inspect      # MCP Inspector (requires OPENAI_ADS_API_KEY not set — still lists tools)
# or with inspector mock:
OPENAI_ADS_API_KEY=sk-ads-test npx -y @modelcontextprotocol/inspector node dist/index.js

Test pattern:

# Mock server in another terminal:
OPENAI_ADS_API_KEY=sk-ads-test OPENAI_ADS_BASE_URL=http://localhost:17892/v1 npx -y chatgpt-ads-manager-mcp
# Then via Inspector: initialize -> tools/list -> tools/call get_ad_account

Publish (maintainers):

npm run build
npm pack --dry-run   # check 87 files, ~42kB
npm publish --access public   # no --provenance for manual publish; use --provenance only in GitHub Actions OIDC
# bump version first: npm version patch && npm publish --access public && git push --follow-tags

API docs: https://developers.openai.com/ads/api-overview + https://developers.openai.com/ads/openapi.json.

License: MIT.

Available Tools

89 tools
activate_adA

Activate a paused ad. Campaign and ad group must also be active + review approved to serve.

Inputs: ad_id (required), ad_account_id.

activate_ad_accountA

Activate the ad account (resume serving). All parent campaigns/ad groups/ads must also be active to serve.

Inputs: ad_account_id.

activate_ad_groupC

Activate a paused ad group.

Inputs: ad_group_id (required), ad_account_id.

activate_campaignA

Activate a paused campaign. All ancestors must be active for ads to serve.

Inputs: campaign_id (required), ad_account_id.

activate_product_feed_sftp_accessB

Activate SFTP access for a product feed (resume ingestion).

Inputs: feed_id (required), ad_account_id.

add_audience_membersA

Add identifiers to an existing custom audience (file or inline). Requires Idempotency-Key and expected_revision. Poll operation via get_audience_operation. Supports up to ~10k inline identifiers; use file for larger.

Inputs: idempotency_key (required), expected_revision (required), custom_audience_id (required), file_id, +4 more.

archive_adC

Archive an ad (terminal).

Inputs: ad_id (required), ad_account_id.

archive_ad_groupC

Archive an ad group (terminal).

Inputs: ad_group_id (required), ad_account_id.

archive_campaignA

Archive a campaign (terminal — cannot be reactivated via activate).

Inputs: campaign_id (required), ad_account_id.

archive_custom_audienceA

Archive a custom audience. Archived audiences cannot be used for targeting.

Inputs: custom_audience_id (required), ad_account_id.

archive_lead_formA

Archive a Lead Form that is not attached to a published Business Agent.

Inputs: lead_form_id (required), ad_account_id.

archive_product_feedA

Archive a product feed. Archived feeds cannot be used for new campaigns.

Inputs: feed_id (required), ad_account_id.

create_adA

Create an ad for an ad group. Requires creative (type/title/body etc.). For chat_card, provide file_id from upload_image. For product_ad_template, use {{product.*}} tokens and omit file_id. Returns ad_id.

Inputs: creative (required), ad_group_id (required), name, status, +3 more.

create_ad_account_spend_limit_windowA

Create a spend limit window with inclusive start and exclusive end. Use to cap spend over a date range.

Inputs: end_time (required), start_time (required), spend_limit_micros (required), ad_account_id.

create_ad_groupA

Create an ad group for a campaign. Returns ad_group_id for chaining to create_ad. Requires campaign_id + bidding_config.

Inputs: name (required), campaign_id (required), bidding_config (required), status, +6 more.

create_ad_previewA

Create a temporary iframe preview for an existing ad. Returns preview URL/html for QA before activating.

Inputs: ad_id (required), ad_account_id.

create_api_keyA

Create an API key scoped to the selected ad account (requires AdsOAuth with write or an existing API key with permission). Returns the new key — store it securely, it won't be shown again.

Inputs: name, ad_account_id.

create_business_agentA

Create a draft Business Agent. Requires name 1–50 + instructions 1–4000. Optionally attach product feeds, connectors, lead form. Publish separately via publish_business_agent.

Inputs: name (required), instructions (required), tools, lead_form, +6 more.

create_campaignA

Create a campaign. Returns campaign_id for chaining to create_ad_group. Common next: create_ad_group with campaign_id. Supports idempotency key to avoid duplicates on retry.

Inputs: name (required), mode, budget, status, +13 more.

create_campaign_hierarchyA

Composite workflow: create a full campaign -> ad group -> ad chain in one call. Useful for quick end-to-end creation. Returns all three IDs. If any step fails, earlier objects remain — use update/archive tools to clean up. Prefer atomic tools (create_campaign, create_ad_group, create_ad) for fine-grained control.

Inputs: ad (required), ad_group (required), campaign (required), ad_account_id, +1 more.

create_conversion_api_keyA

Create a Conversions API key for the ad account (used to send server-side events via bzr.openai.com outside this MCP). Returns api_key — store securely, single display.

Inputs: name (required), ad_account_id.

create_conversion_event_settingA

Create a conversion event setting linking an event type to source pixel(s). Used for conversions bidding (bidding_type=conversions) and conversion_event_setting_ids on campaigns. Requires name + event_type + source_ids.

Inputs: name (required), event_type (required), source_ids (required), ad_account_id, +2 more.

create_conversion_pixelA

Create a conversion pixel (client data source) for the ad account. Returns pixel id (pid) used for event attribution and listing sampled events. Chain to create_conversion_api_key and create_conversion_event_setting.

Inputs: name (required), client_type, ad_account_id.

create_custom_audienceA

Create a custom audience from an uploaded file (provide file_id) or as empty/small audience if enabled. Processing is async — poll via get_custom_audience until published. Returns custom_audience_id.

Inputs: name (required), file_id, filename, mimetype, +5 more.

create_lead_formA

Create a draft Lead Form. Requires name 1–256 + fields 3–5 (each: field_id, field_type text|choice, label, required, options for choice). Publish after creation.

Inputs: name (required), fields (required), description, ad_account_id, +1 more.

create_lead_sync_subscriptionA

Provision lead delivery to a managed webhook endpoint for an ad account. Requires Idempotency-Key and destination URL. Leads will be POSTed with Standard Webhooks HMAC signature.

Inputs: url (required), idempotency_key (required), ad_account_id, ad_account_ids.

create_partner_data_uploadB

Create an Ads partner-data upload (for partner integrations). Returns upload id for polling via get_partner_data_upload.

Inputs: file_id, upload_type, ad_account_id.

create_product_feedA

Create a product feed for the ad account (merchant catalog). For SFTP-fetched catalogs, configure SFTP after. Use list_product_feeds to see existing.

Inputs: url, name, ad_account_id.

create_product_feed_sftp_accessA

Create or replace SFTP access credentials for a product feed. Returns credentials to configure your SFTP client.

Inputs: feed_id (required), password, ad_account_id.

create_test_lead_submissionA

Queue a synthetic signed lead-sync webhook test delivery for a Lead Form. Requires Idempotency-Key. Useful to validate webhook handling before going live.

Inputs: lead_form_id (required), idempotency_key (required), field_values, ad_account_id.

delete_ad_account_spend_limit_windowA

Delete an active or scheduled spend limit window before it ends.

Inputs: window_id (required), ad_account_id.

delete_lead_sync_subscriptionA

Delete a lead-sync subscription to stop webhook delivery.

Inputs: subscription_id (required), ad_account_id.

get_adA

Get a single ad by ID. Check review_status to monitor approval (typically minutes).

Inputs: ad_id (required), include, ad_account_id.

get_ad_accountA

Get metadata for the ad account associated with the API key. Use to verify auth, check timezone/currency/review status. No chaining needed — call first to confirm key works.

Inputs: ad_account_id.

get_ad_account_insightsA

Get ad account insights aggregated by time granularity. Attribution for current local day is preliminary. Use time_ranges + fields + segments for breakdowns. Paginated (limit/after/before).

Inputs: sort, after, limit, before, +9 more.

get_ad_account_spend_limit_windowsA

View spend limit windows (inclusive start, exclusive end, ordered by start ascending). Use to audit or plan budget caps.

Inputs: ad_account_id.

get_ad_groupB

Get a single ad group by ID.

Inputs: ad_group_id (required), include, ad_account_id.

get_ad_group_insightsB

Get ad group insights. Chain from list_ad_groups -> ad_group_id.

Inputs: ad_group_id (required), sort, after, limit, +10 more.

get_ad_insightsB

Get ad insights for a single ad. Check creative-level performance.

Inputs: ad_id (required), sort, after, limit, +10 more.

get_audience_operationA

Retrieve lifecycle state of a custom audience mutation (add/remove/replace/merge). Poll with backoff. States: processing → succeeded/failed. Save operation_id from mutation response.

Inputs: operation_id (required), custom_audience_id (required), ad_account_id.

get_business_agentA

Get a Business Agent by ID.

Inputs: business_agent_id (required), ad_account_id.

get_campaignA

Get a single campaign by ID. Use include=[serving_issues] to audit delivery problems. Returned id chains to ad group creation.

Inputs: campaign_id (required), include, ad_account_id.

get_campaign_insightsA

Get campaign insights. Chain from list_campaigns -> campaign_id. Same params as ad account insights but scoped to one campaign.

Inputs: campaign_id (required), sort, after, limit, +10 more.

get_conversion_insightsA

Get attributed conversion totals or daily values. POST /conversions/insights. Requires aggregation_level + time_ranges. Use breakdown (device/country) for segments. group_by_entity splits per campaign/ad_group/ad.

Inputs: time_ranges (required), aggregation_level (required), breakdown, entity_ids, +4 more.

get_custom_audienceA

Get a custom audience by ID. Check processing state and membership_revision before mutations.

Inputs: custom_audience_id (required), ad_account_id, matched_count_granularity.

get_lead_formA

Get a Lead Form by ID. Optionally specify rev_id for a specific revision.

Inputs: lead_form_id (required), rev_id, ad_account_id.

get_lead_sync_subscriptionB

Get a lead-sync subscription by ID.

Inputs: subscription_id (required), ad_account_id.

get_oauth_meA

Return the authenticated user's stable opaque ID (OAuth only). Useful for partner flows to verify token identity.

Inputs: no named parameters.

get_partner_data_uploadA

Get an Ads partner-data upload by ID (e.g., pdu_...). Poll to check processing status.

Inputs: upload_id (required), ad_account_id.

get_product_feed_sftp_accessA

Get SFTP access details for a product feed (host, username, path). Use to configure catalog uploads.

Inputs: feed_id (required), ad_account_id.

list_ad_accountsA

List ad accounts accessible to the authenticated key/OAuth token. Returns accounts with ids for use as ad_account_id in other tools.

Inputs: ad_account_id.

list_ad_groupsA

List ad groups for the ad account, optionally filtered by campaign_id. Use returned ad_group_id to create ads or fetch insights.

Inputs: name, after, limit, order, +4 more.

list_adsA

List ads for the ad account, optionally filtered by campaign_id or ad_group_id. Use ad_id for get_ad / insights / preview.

Inputs: name, after, limit, order, +5 more.

list_business_agentsB

List Business Agents for the ad account. Each has id, name, status draft/published, etc.

Inputs: ad_account_id.

list_business_agent_toolsA

List eligible Business Agent tools installed for the authenticated API project. Use to discover connectors/tools available for business agent creation.

Inputs: no named parameters.

list_campaignsA

List campaigns for the ad account. Paginated. Use returned campaign_id with get_campaign, update_campaign, create_ad_group, and insights tools. Filter by name if needed.

Inputs: name, after, limit, order, +3 more.

list_conversion_eventsA

List recent sampled conversion events for a pixel (requires pid). Up to 50 per call. Use to verify ingestion from bzr.openai.com.

Inputs: pid (required), limit, ad_account_id.

list_conversion_event_settingsB

List conversion event settings for the ad account. Use IDs with campaign conversion_event_setting_ids and conversions bidding.

Inputs: after, limit, order, before, +1 more.

list_conversion_pixelsA

List conversion pixels and connected pixel IDs for the ad account. Use pid from here with list_conversion_events.

Inputs: after, limit, order, before, +1 more.

list_custom_audiencesB

List custom audiences. Filter by intended_use, ids, or policy_revision for eligibility. Returns audiences with membership_revision for mutations. Paginated.

Inputs: after, limit, order, before, +5 more.

list_lead_formsC

List Lead Forms for the ad account.

Inputs: ad_account_id.

list_lead_sync_subscriptionsC

List lead-sync subscriptions for an ad account. Requires ad_account_id query param.

Inputs: ad_account_id (required).

list_product_feedsB

List product feeds for the ad account. Use feed_id with query/patch/sftp tools.

Inputs: after, limit, order, before, +2 more.

list_product_feed_uploadsB

List recent product feed uploads (ingestion history). Useful to debug catalog fetch issues.

Inputs: after, limit, before, ad_account_id.

merge_custom_audiencesA

Create a new audience containing all matched members from 2–64 source audiences. Independent copy. Requires Idempotency-Key.

Inputs: name (required), idempotency_key (required), custom_audience_ids (required), description, +1 more.

patch_product_feed_productsA

Update product availability and prices for a feed (delta without full SFTP re-upload). Provide product patches with item identifiers.

Inputs: feed_id (required), products (required), ad_account_id.

pause_adC

Pause an active ad.

Inputs: ad_id (required), ad_account_id.

pause_ad_accountA

Pause the ad account (stop all serving). Reversible via activate_ad_account.

Inputs: ad_account_id.

pause_ad_groupC

Pause an active ad group.

Inputs: ad_group_id (required), ad_account_id.

pause_campaignA

Pause an active campaign. Reversible via activate_campaign.

Inputs: campaign_id (required), ad_account_id.

pause_product_feed_sftp_accessB

Pause SFTP access for a product feed (stop ingestion).

Inputs: feed_id (required), ad_account_id.

poll_audience_operationA

Helper to poll a custom audience mutation until terminal. Calls get_audience_operation once and returns current state. Call repeatedly with backoff (processing -> succeeded/failed). Does NOT loop internally — agent controls retry timing to respect rate limits.

Inputs: operation_id (required), custom_audience_id (required), ad_account_id.

preview_business_agentA

Preview a response from a Business Agent. Useful for QA before publishing. Provide a test message.

Inputs: message (required), business_agent_id (required), ad_account_id, conversation_id.

publish_business_agentA

Publish a Business Agent draft to make it live. Ensure preview looks good first.

Inputs: business_agent_id (required), ad_account_id.

publish_lead_formB

Publish the current Lead Form draft. After publishing, the form can be attached to a Business Agent.

Inputs: lead_form_id (required), ad_account_id.

query_product_feed_productsA

List products in a feed matching ad group product filters. Use to validate targeting before creating ad_group with product_set.

Inputs: feed_id (required), after, limit, filters, +1 more.

remove_audience_membersA

Remove identifiers from a custom audience (file or inline). Requires Idempotency-Key and expected_revision. Poll via get_audience_operation.

Inputs: idempotency_key (required), expected_revision (required), custom_audience_id (required), file_id, +4 more.

replace_audience_membersA

Replace all members of a custom audience using an uploaded file and current revision. Requires Idempotency-Key. Poll via get_audience_operation.

Inputs: file_id (required), idempotency_key (required), expected_revision (required), custom_audience_id (required), +6 more.

search_geo_lookupA

Search DMA and standard region codes for advertiser geo targeting. Use returned location IDs with campaign targeting.locations.include. Chain: search_geo_lookup {q:'California'} -> create_campaign {targeting:{locations:{include:[...ids]}}}

Inputs: q (required), limit, ad_account_id.

update_adB

Update an ad by ID. Only provided fields are updated.

Inputs: ad_id (required), name, status, creative, +2 more.

update_ad_account_brandA

Update ad account brand metadata (name, url, etc.). Requires account be enabled for programmatic brand updates or it will 403. Chain after get_ad_account to see current values.

Inputs: url, name, preview_url, ad_account_id.

update_ad_account_negative_keywordsA

Replace account-level negative keywords used for ad eligibility. Provide full desired list — this is a replace, not append. Use to block unwanted contexts.

Inputs: negative_keywords (required), ad_account_id.

update_ad_account_spend_limit_windowA

Edit a spend limit window (inclusive start, exclusive end). Provide window_id from get/create.

Inputs: window_id (required), end_time, start_time, ad_account_id, +1 more.

update_ad_groupC

Update an ad group by ID.

Inputs: ad_group_id (required), name, status, description, +5 more.

update_business_agentA

Replace a Business Agent's name and config and save as draft. Omitted optional fields reset to defaults (except lead_form preserved if omitted; send null to unlink). Requires full desired state.

Inputs: name (required), instructions (required), business_agent_id (required), tools, +7 more.

update_campaignA

Update a campaign by ID. Only provided fields are updated. Omitted optional fields reset to defaults except where noted. Send null to clear description/start_time/end_time.

Inputs: campaign_id (required), name, budget, status, +10 more.

update_lead_formB

Save a new draft revision for a Lead Form. Requires expected_draft_revision_id for conflict detection.

Inputs: lead_form_id (required), name, fields, description, +3 more.

upload_audience_fileA

Upload a file for custom audience creation (CSV/TXT up to 500MB). Returns file_id (oaisdmntci_...) to use in create_custom_audience or add_audience_members. Provide file_base64 (base64 of CSV/TXT). Purpose is always custom_audience.

Inputs: filename (required), file_base64 (required), mimetype, ad_account_id.

upload_imageA

Upload a creative image for ads. Provide EITHER image_url (https) OR image_base64 (data). image_url is SSRF-guarded (https only, no private hosts). Returns file_id to use in create_ad creative.file_id. For chat_card ads, upload first then create_ad.

Inputs: filename, image_url, image_base64, ad_account_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 89 tools

    Disambiguation4/5

    Most tools are clearly scoped to specific resources and actions (campaign vs ad group vs ad, pause vs activate vs archive). The main boundary blur is between get_audience_operation and poll_audience_operation, which both serve the same polling purpose, and create_campaign_hierarchy partially duplicates the create_campaign/create_ad_group/create_ad sequence.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern using snake_case throughout, e.g., list_campaigns, get_campaign, create_campaign, update_campaign, pause_campaign, archive_campaign. Even longer names like create_ad_account_spend_limit_window remain predictable.

    Tool Count1/5

    89 tools is an extreme count, far exceeding the 50+ threshold for a cohesive tool set. While the domain is broad, several helpers like poll_audience_operation and create_campaign_hierarchy inflate the surface without adding distinct capabilities.

    Completeness3/5

    Core ad account, campaign, ad group, ad, audience, and lead form lifecycles are well covered. However, some subdomains are incomplete: conversion pixels/event settings have no update or delete, business agents cannot be archived/deleted, and lead-sync subscriptions lack update support.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables management of OpenAI Ads campaigns, ad groups, ads, and insights through MCP, with approval-gated live mutations for safe write operations.
      157 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to manage OpenAI Ads campaigns, ad groups, creatives, custom audiences, conversion tracking via web pixel and CAPI, and run tracking audits through the OpenAI Ads Advertiser API.
      43
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables managing mock Facebook Ads Manager-style campaigns through MCP, including querying nested campaign/ad set/ad performance data, flagging underperformers, drafting budget, creative, and pause/resume proposals, and applying changes only after human review or dashboard approval.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to create, manage, and optimize advertising campaigns across 14 ad and measurement platforms through a single MCP endpoint, with over 530 executable tools.
      4
      MIT