OpenAI Ads & Conversion Intelligence MCP Server
Provides integration with the OpenAI Ads Advertiser API, enabling management of ad accounts, campaigns, ad groups, ads, creative assets, conversion tracking, custom audiences, product feeds, bulk operations, and delivery/conversion insights.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenAI Ads & Conversion Intelligence MCP Server Run a tracking audit and summarize any conversion issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenAI Ads & Conversion Intelligence MCP Server š
An enterprise-grade Model Context Protocol (MCP) server connecting AI agents (Antigravity, Claude Desktop, Cursor, custom agents) directly to the OpenAI Ads Advertiser API and conversion measurement ecosystem.
Built with TypeScript and @modelcontextprotocol/sdk, this server provides complete campaign management, ad creation, measurement configuration, custom audiences, delta product feeds, bulk operations, and high-level tracking audit intelligence.
šļø System Architecture
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā MCP Host / Client ā
ā (Claude Desktop, Cursor, Antigravity, AI Agents) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā JSON-RPC 2.0 (stdio)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā OPENAI ADS MCP SERVER ā
ā ā
ā š ļø Tool Layer (Zod Validated Inputs) ā
ā ⢠Account & Brand ⢠Campaigns ⢠Ad Groups & Ads ā
ā ⢠Delivery Insights ⢠Conversions ⢠Custom Audiences ā
ā ⢠Product Feeds ⢠Bulk Mutations ⢠Tracking Audit ā ā
ā ā
ā š¦ Service Layer ā
ā ⢠AccountService ⢠CampaignService ⢠AdGroupService ā
ā ⢠AdService ⢠InsightService ⢠ConversionService ā
ā ⢠AudienceService ⢠FeedService ⢠BulkService ā
ā ⢠GeoService ⢠AuditService ā ā
ā ā
ā š Core Client (`OpenAIAdsClient`) ā
ā ⢠Bearer token authentication via $OPENAI_ADS_API_KEY ā
ā ⢠Typed errors (`OpenAIAdsApiError`) and standard response parsing ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā HTTPS
ā¼
OpenAI Ads Advertiser API (v1)
https://api.ads.openai.com/v1Related MCP server: OpenAI Ads MCP
ā” Features & Capabilities
Full Campaign Lifecycle: Create, list, retrieve, update, pause, activate, or archive campaigns. Supports CPM (
impressions), CPC (clicks), and oCPC (conversions).Context Hints: Leverage conversational AI ad placement with free-form keywords and placement descriptions (
context_hints).Creative Asset Management: Upload creative image cards (
chat_card) or product catalog templates (product_ad_template). Generate 24-hour web preview links.Conversion Tracking & oCPC: Create web pixels (with automatic advanced matching), generate server-side CAPI keys, define conversion event settings, and stream live 15-minute browser events for testing.
Custom Audiences: Upload first-party customer lists (email, phone, SHA256, GAID), perform incremental additions/removals, replace memberships with optimistic concurrency (
expected_revision), and configure bid adjustments.Delta Product Feeds: Instantly update stock availability (
in_stock/out_of_stock), price, and title for catalog variants without re-uploading entire feeds.Bulk Mutations: Asynchronously batch up to 1,000 operations across campaigns, ad groups, and ads.
Deep Performance Insights: Query delivery metrics (impressions, clicks, spend, CTR, CPC, CPM) segmented by product, country, or device, plus attributed click-through and view-through conversions.
ā Tracking Audit & Intelligence: Built-in automated audits checking brand review status, conversion event settings, recent pixel event streams, and campaign CPA/ROAS health.
š Quickstart
1. Prerequisites
Node.js: v18.0.0 or higher (v20+ recommended).
OpenAI Ads Account: An active ad account and an API key generated from the Settings tab in OpenAI Ads Manager.
2. Installation & Build
# Clone or navigate to the project directory
cd openai-ads-mcp
# Install dependencies
npm install
# Compile TypeScript
npm run build3. Environment Configuration
Create a .env file in the project root:
OPENAI_ADS_API_KEY=your_actual_ads_api_key_here
OPENAI_ADS_API_BASE_URL=https://api.ads.openai.com/v1š Host Configuration
š Google Antigravity
Add to your global Antigravity MCP configuration file at ~/.gemini/config/mcp_config.json:
{
"mcpServers": {
"openai-ads-mcp": {
"command": "node",
"args": [
"C:/Users/HP/.gemini/antigravity/scratch/openai-ads-mcp/dist/index.js"
],
"env": {
"OPENAI_ADS_API_KEY": "your_openai_ads_api_key_here"
}
}
}
}š¬ ChatGPT (Desktop / Developer Mode)
Add to your ChatGPT MCP configuration (~/.chatgpt/mcp.json or Developer Mode settings):
{
"mcpServers": {
"openai-ads": {
"command": "node",
"args": [
"C:/Users/HP/.gemini/antigravity/scratch/openai-ads-mcp/dist/index.js"
],
"env": {
"OPENAI_ADS_API_KEY": "your_openai_ads_api_key_here"
}
}
}
}ā” OpenAI Codex / Codex CLI
Add to your Codex MCP configuration (~/.codex/config.json or codex-mcp.json):
{
"mcpServers": {
"openai-ads": {
"command": "node",
"args": [
"C:/Users/HP/.gemini/antigravity/scratch/openai-ads-mcp/dist/index.js"
],
"env": {
"OPENAI_ADS_API_KEY": "your_openai_ads_api_key_here"
}
}
}
}š» Cursor (.cursor/mcp.json)
{
"mcpServers": {
"openai-ads": {
"command": "node",
"args": [
"C:/Users/HP/.gemini/antigravity/scratch/openai-ads-mcp/dist/index.js"
],
"env": {
"OPENAI_ADS_API_KEY": "your_openai_ads_api_key_here"
}
}
}
}š£ Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"openai-ads": {
"command": "node",
"args": [
"C:/Users/HP/.gemini/antigravity/scratch/openai-ads-mcp/dist/index.js"
],
"env": {
"OPENAI_ADS_API_KEY": "your_openai_ads_api_key_here"
}
}
}
}š ļø Tool Catalog Reference (43 Tools)
š¢ Account & Brand
Tool | Description |
| Retrieve account ID, name, timezone, currency, and brand review approval. |
| Update display name or assign a brand favicon |
š¢ Campaigns
Tool | Description |
| List campaigns with pagination and sorting. |
| Fetch campaign metadata by ID. |
| Create a campaign ( |
| Update lifetime budget, schedule timestamps, status, or description. |
| Explicitly |
| Deep-copies an existing campaign, ad groups, and ads into a new campaign structure. |
š„ Ad Groups
Tool | Description |
| List ad groups belonging to a campaign. |
| Fetch ad group details by ID. |
| Create an ad group with |
| Update ad group parameters, bids, or context hints. |
| Explicitly |
š Ads & Creatives
Tool | Description |
| Upload a remote image URL to obtain a reusable |
| List ads in an ad group. |
| Fetch ad creative and |
| Create a |
| Generate a 24-hour web preview URL for an ad. |
| Explicitly |
| AI brainstorming tool generating realistic ChatGPT user prompt queries & conversational copy. |
š Insights & Reporting
Tool | Description |
| Query impressions, clicks, spend, CTR, CPC, CPM across account, campaign, ad group, or ad scopes. |
| Query attributed click-through and view-through conversions and revenue. |
šÆ Measurement & Conversions
Tool | Description |
| Create a web pixel with automatic advanced matching. |
| Inspect up to 50 events received in the last 15 minutes for live testing. |
| Generate a server-side Conversions API key (CAPI). |
| Define conversion goals ( |
| List all configured conversion definitions in the account. |
| Dispatch test or live server-side conversion events via CAPI with automatic hashing. |
š„ Custom Audiences
Tool | Description |
| List audiences filtered by eligibility ( |
| Retrieve audience status, privacy size range, and revision. |
| Create an audience from a file or initialize an empty list. |
| Add or remove members inline or via delta file with optimistic revision check. |
| Union 2 to 64 existing audiences into a new independent audience. |
| Permanently archive a custom audience. |
| Poll status of asynchronous membership mutations. |
| Validates, normalizes, and SHA-256 hashes raw customer emails/phones with auto-upload. |
šļø Product Feeds & Delta Updates
Tool | Description |
| Delta update prices, titles, or availability ( |
š¦ Bulk Operations
Tool | Description |
| Batch up to 1,000 create/update operations in an asynchronous job. |
| Poll bulk job execution and fetch per-operation results. |
š Targeting
Tool | Description |
| Search DMAs, regions, and countries for location IDs. |
ā Tracking Intelligence & Anomaly Guardrails
Tool | Description |
| Deep diagnostic of brand approval, configured event settings, and real-time pixel health. |
| Evaluates spend, CTR, CPC, conversions, CPA, and provides actionable recommendations. |
| Budget protector guardrail detecting zero-conversion spend drain and CPA runaway. |
š¬ Example AI Interactions
1. Audit Conversion Setup
"Run an audit on my OpenAI Ads conversion tracking. Are my pixels receiving events, and are my event settings properly configured for conversion campaigns?"
2. Launch an oCPC Campaign
"Create an oCPC campaign named 'Spring Launch' optimizing for purchases with a $50 daily budget. Target the San Francisco DMA and create an ad group with a $25 CPA bid."
3. Performance Review
"Analyze the performance of my top campaigns over the last 14 days. Show me clicks, spend, CTR, and CPA, and recommend optimizations."
4. Audience Management
"Create a new custom audience of high-value purchasers and exclude them from my prospecting campaign."
š License
MIT
Available Tools
43 toolsanalyze_campaign_performanceAnalyze Campaign Performance & ROASB
Analyzes campaign metrics (impressions, clicks, spend, CTR, CPC, conversions, CPA). Provides diagnostic assessments (STRONG, MODERATE, NEEDS_ATTENTION) and actionable optimization recommendations.
Inputs: campaign_id (required).
archive_custom_audienceArchive Custom AudienceA
Permanently archive a custom audience. Archived audiences cannot be restored.
Inputs: custom_audience_id (required).
audit_conversion_trackingAudit Conversion Tracking HealthA
Comprehensive tracking audit. Inspects ad account brand approval, configured conversion event settings, and optionally polls the 15-minute live pixel stream to diagnose missing events, tag misconfigurations, and CAPI readiness.
Inputs: pixel_id.
clone_campaign_structureClone Campaign Structure & HierarchyA
Deep-copies an existing campaign along with all its child ad groups and ads into a new campaign (created in paused state by default). Allows overriding name, budget, or flight dates.
Inputs: source_campaign_id (required), new_name, include_ads, activate_after_cloning, +1 more.
create_adCreate AdA
Create an ad in an ad group. Supports 'chat_card' (title 3-50 chars, body max 100 chars, destination target_url, and uploaded file_id) or 'product_ad_template' (for product feed campaigns).
Inputs: body (required), name (required), title (required), status (required), +6 more.
create_ad_groupCreate Ad GroupA
Create an ad group under a campaign. Billing event must match campaign objective ('impression' for CPM; 'click' for CPC and oCPC). max_bid_micros is in millionths (e.g. 60000 = $0.06/event or $60 CPM; 100000000 = $100 CPA bid).
Inputs: name (required), status (required), campaign_id (required), max_bid_micros (required), +5 more.
create_campaignCreate CampaignA
Create an ad campaign. Note: lifetime_spend_limit_micros is in currency millionths (e.g. 25000000 = $25.00 USD). Bidding type cannot be changed after creation.
Inputs: name (required), status (required), lifetime_spend_limit_micros (required), end_time, +6 more.
create_conversion_event_settingCreate Conversion Event SettingA
Defines an active conversion goal (e.g. 'order_created', 'lead_created', 'registration_completed') bound to a pixel source ID. Required for oCPC conversion-optimized campaigns.
Inputs: name (required), source_id (required), event_type (required), custom_event_name, +1 more.
create_conversions_api_keyCreate Conversions API Key (CAPI)A
Generate a server-side Conversions API key to send conversion events directly from backend servers. Note: store securely in server secrets.
Inputs: name (required).
create_custom_audienceCreate Custom AudienceB
Creates a new custom audience. Can create an empty audience for incremental builds or attach an uploaded file_id.
Inputs: name (required), file_id, filename, mimetype, +4 more.
create_web_pixelCreate Web PixelA
Creates a web conversion source and returns both an internal source ID (clidsrc_*) and a public pixel_id. Web pixels automatically support automatic advanced matching.
Inputs: name (required).
detect_spend_anomaliesDetect Spend & CPA Anomalies (Guardrail)A
Scans recent delivery and conversion metrics for runaway spend, zero-conversion budget drain, low-CTR creative burnout, and abnormal CPA spikes across campaigns. Recommends immediate remediation actions.
Inputs: campaign_id, lookback_days, max_cpa_multiplier, zero_conversion_spend_threshold_usd.
generate_ad_intent_queriesGenerate Conversational Ad Intent Queries & CopyB
Generates realistic, high-intent ChatGPT user queries (custom_intent_queries) and conversational sponsored ad copy tailored to your product, audience, and value propositions.
Inputs: key_benefits (required), product_name (required), target_audience (required), landing_page_url (required), +3 more.
get_adGet AdA
Fetch an ad by ID, including creative details and review_status.
Inputs: ad_id (required).
get_ad_accountGet Ad Account MetadataA
Fetches the OpenAI Ads account associated with the configured API key, including ID, name, destination URL, timezone, currency, and brand review status.
Inputs: no named parameters.
get_ad_groupGet Ad GroupA
Fetch an ad group by its ID.
Inputs: ad_group_id (required).
get_audience_operation_statusGet Audience Operation StatusA
Poll the status of an asynchronous membership operation (add, remove, replace, merge) until 'succeeded' or 'failed'.
Inputs: operation_id (required), custom_audience_id (required).
get_bulk_mutation_job_statusGet Bulk Job Status & OperationsA
Poll bulk job progress (pending, in_progress, completed, partially_failed, failed) and inspect per-operation execution results.
Inputs: job_id (required), after, limit, include_operations.
get_campaignGet CampaignA
Fetch a single OpenAI Ads campaign by its ID.
Inputs: campaign_id (required).
get_conversion_insightsGet Conversion InsightsB
Retrieve attributed conversion totals (conversions, click_through_conversions, view_through_conversions). 'conversions' is always equal to 'click_through_conversions'. View-through conversions use a fixed 1-day impression window for reporting.
Inputs: end_time (required), start_time (required), aggregation_level (required), entity_ids.
get_custom_audienceGet Custom AudienceA
Retrieve audience status, privacy-preserving size ranges (e.g. under_25k, 25k_100k), and current membership_revision.
Inputs: custom_audience_id (required).
get_delivery_insightsGet Delivery InsightsB
Retrieve advertising performance metrics (impressions, clicks, spend, CTR, CPC, CPM). Supports aggregation_level ('ad_account', 'campaign', 'ad_group', 'ad'), time_granularity ('hourly', 'daily', 'monthly', 'none'), segments (['product'], ['country'], ['device']), and zero-impression items.
Inputs: scope (required), after, limit, fields, +6 more.
inspect_recent_pixel_eventsInspect Recent Pixel EventsA
Test and verify incoming browser pixel events. Returns up to 50 raw events received by OpenAI from the JavaScript pixel SDK during the previous 15 minutes.
Inputs: pixel_id (required).
list_ad_groupsList Ad GroupsB
List ad groups for a specific parent campaign ID.
Inputs: campaign_id (required), after, limit, order.
list_adsList AdsC
List ads for a specific ad group ID.
Inputs: ad_group_id (required), after, limit, order.
list_campaignsList CampaignsA
List campaigns in the current OpenAI Ads account with pagination.
Inputs: after, limit, order, before.
list_conversion_event_settingsList Conversion Event SettingsB
List all conversion definitions configured for the current ad account.
Inputs: after, limit.
list_custom_audiencesList Custom AudiencesB
List custom audiences for the current ad account. Use 'intended_use' ('inclusion', 'exclusion', 'bid_multiplier') to filter only eligible audiences.
Inputs: limit, intended_use, custom_audience_ids.
merge_custom_audiencesMerge Custom AudiencesA
Merges 2 to 64 existing, ready audiences in the same ad account into a new union audience.
Inputs: name (required), custom_audience_ids (required), idempotency_key.
mutate_audience_membershipAdd or Remove Audience MembersA
Add or remove customer identifiers from an existing custom audience. Accepts inline identifiers or an uploaded file_id. Returns an asynchronous operation ID.
Inputs: action (required), custom_audience_id (required), file_id, identifiers, +2 more.
prepare_custom_audience_payloadPrepare & Hash Custom Audience PayloadA
Normalizes raw emails (trimmed, lowercase) and phone numbers (E.164 standard) into SHA-256 hashes per OpenAI specification. Optionally uploads the hashed members directly to a custom audience.
Inputs: action, emails, phones, auto_upload, +1 more.
preview_adPreview AdA
Generate a 24-hour temporary web preview URL for an existing ad.
Inputs: ad_id (required).
search_geo_locationsSearch Geo LocationsA
Search targetable locations (countries, regions, and DMAs) by keyword query to obtain location IDs for campaign targeting.
Inputs: query (required), limit.
send_test_conversion_eventSend Test Conversion Event (CAPI Dispatcher)A
Dispatches a test or live server-side conversion event (e.g., 'order_created', 'lead_created', 'add_to_cart') via the OpenAI Conversions API. Automatically hashes plain emails/phones with SHA-256 and attaches deduplication tokens.
Inputs: event_name (required), obref, value, currency, +5 more.
set_ad_group_stateSet Ad Group StateA
Activate, pause, or archive an ad group. Archiving is irreversible.
Inputs: action (required), ad_group_id (required).
set_ad_stateSet Ad StateB
Activate, pause, or archive an ad. Archiving is permanent.
Inputs: ad_id (required), action (required).
set_campaign_stateSet Campaign StateA
Explicitly activate, pause, or archive a campaign. Archiving is irreversible.
Inputs: action (required), campaign_id (required).
submit_bulk_mutation_jobSubmit Bulk Mutation JobA
Submits an asynchronous bulk job with up to 1,000 operations (campaign.create/update, ad_group.create/update, ad.create/update). Entities can link via campaign_idempotency_key and ad_group_idempotency_key.
Inputs: operations (required), validate_only, idempotency_key, partial_failure.
update_ad_account_brandUpdate Account Brand MetadataA
Updates the ad account display name or assigns a brand favicon file_id, triggering an automatic brand review required for ad serving.
Inputs: name, favicon_file_id.
update_ad_groupUpdate Ad GroupC
Update ad group name, description, context_hints, status, or bidding_config.
Inputs: ad_group_id (required), name, status, description, +3 more.
update_campaignUpdate CampaignB
Update campaign budget, schedule, status, or description. Note: bidding_type cannot be updated.
Inputs: campaign_id (required), name, status, end_time, +3 more.
update_feed_product_variantsDelta Update Product Feed VariantsA
Delta update prices, titles, or stock availability for existing variants in a linked merchant feed without re-uploading the entire catalog.
Inputs: feed_id (required), products (required).
upload_creative_assetUpload Creative Asset from URLA
Upload a remote image URL to OpenAI Ads and receive a reusable file_id for ads (chat_card) or brand review (account_favicon).
Inputs: image_url (required), purpose.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 43 tools
Most tools are clearly separated by resource and action, but there is meaningful overlap among the analytics/insight tools (get_delivery_insights, get_conversion_insights, analyze_campaign_performance, detect_spend_anomalies) and between update_campaign and set_campaign_state, both of which can modify campaign status.
All tools consistently follow a snake_case verb_noun pattern, with clear conventions for CRUD (get/list/create/update) and state changes (set_*_state). No mixed casing or arbitrary verb styles are present.
43 tools is a heavy surface for an MCP server, well above the 25-tool threshold. While the breadth reflects the ads domain, several analytics, audit, and insight tools could be consolidated without losing capability.
The server covers campaign, ad group, ad, audience, conversion tracking, and bulk operations well. However, there are notable lifecycle gaps: no update_ad, no update/delete for conversion event settings or web pixels, and limited management of conversion sources beyond creation.
Maintenance
Related MCP Connectors
OpenAI Ads MCP for ChatGPT Ads campaigns, creatives, audiences, insights, and conversions.
60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Run Meta, Google, TikTok, LinkedIn, Microsoft, Reddit, X and Pinterest ads from your AI agent.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to manage Facebook and Instagram advertising campaigns through the Meta Marketing API. Supports full campaign lifecycle management, performance analytics, audience targeting, and creative optimization.-
- AlicenseNot gradedqualityDmaintenanceEnables management of OpenAI Ads campaigns, ad groups, ads, and insights through MCP, with approval-gated live mutations for safe write operations.157 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create, manage, and automate Meta (Facebook/Instagram) ads campaigns via the Marketing API, with safe defaults and AI-generated creative.1MIT
- AlicenseBqualityCmaintenanceEnables managing ChatGPT Advertiser campaigns from MCP-capable agents, including campaign creation, creative uploads, audience management, conversions setup, and insights retrieval.8931 npmMIT