ChatGPT Ads MCP server
This MCP server lets an AI client read and optionally manage a single ChatGPT Ads account through its Advertiser API, with writes disabled by default and confirmation-gated.
Read account details, campaigns, ad groups, ads, creatives, performance insights, locations, audit logs, spend limits, landing-page crawl evidence, conversion settings/pixels/events/insights, product feeds/uploads/settings/products, custom audiences and operations, and Bulk API jobs.
Inspect write schemas, write context, and mutation previews/receipts before changing anything.
When writes are enabled, create/update/pause/archive campaigns, ad groups, and ads; rename entities; create ad previews; upload images; create conversion settings/pixels; create/update/archive product feeds; and submit Bulk API jobs.
Writes preview by default, require a confirmation token, check native state before applying, use idempotency keys, and flag uncertain outcomes as UNKNOWN for receipt lookup rather than resubmission.
Activation that can start delivery/spend requires a separate
OPENAI_ADS_ENABLE_ACTIVATION=trueopt-in.Run locally over stdio with
OPENAI_ADS_API_KEYandOPENAI_ADS_ACCOUNT_ID; all tools are scoped to the configuredadacct_account.Includes a resource guide covering account scope, write flow, units, rate limits, metrics, levels, breakdowns, and attribution.
Provides tools for interacting with the ChatGPT Ads (OpenAI Ads) Advertiser API, enabling reading and managing ad accounts, campaigns, ad groups, ads, creatives, insights, conversions, product feeds, custom audiences, audit logs, spend limits, and Bulk API jobs.
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., "@ChatGPT Ads MCP server Show me last week's campaign performance and conversions."
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.
ChatGPT Ads MCP server
Bring your ChatGPT Ads account into your MCP client.
Read campaigns, performance and conversions, and prepare changes for the ad account your API key belongs to.
Watch the film · What's new · Install · Tool reference · Try hosted getmcpads

The film shows hosted getmcpads with sample data. Its MCP Apps, from creative galleries and alerts to Google Sheets exports and bulk launches, belong to the hosted product. This repository provides the standalone native API tools.
30 read tools · 28 write tools, disabled by default.
Run locally with your own Advertiser API key and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the ChatGPT Ads API. For managed connections, including supported ChatGPT setups, use the hosted option.
What's new
v1.0.2: Maintainer metadata update · November 8, 2026
List the getmcpads team as maintainer in
package.json, the README andSOURCE_SYNC.md.No change to tools, parameters, descriptions or runtime behaviour.
Earlier releases
Version | Date | Highlights |
1.0.1 | October 26, 2026 | Zod 4 security update |
1.0.0 | October 23, 2026 | First standalone release |
Source synchronization: SOURCE_SYNC.md.
Upgrade notes
Requires Node.js 22.23.4 or later on the 22 line, 24.22.1 or later on the 24 line, or 26.12.1 or later. These releases carry the October 2026 security fixes, and the server prints a warning on stderr when started on an older runtime. CI covers Node 22, 24 and 26. Writes remain optional and require explicit confirmation. Hosted creative integrations and MCP Apps UI are outside this release.
Related MCP server: OpenAI Ads MCP
Install this release
This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version; unpinned npx examples later in this document select the version currently available on npm.
git clone --branch v1.0.2 --depth 1 https://github.com/get-mcp-ads/chatgpt-ads-mcp-server.git
cd chatgpt-ads-mcp-server
npm ci
npm run buildConfigure your MCP client to run node with the absolute path to dist/cli.js and the environment variables documented below. With the npm package, a client configuration looks like this:
{
"mcpServers": {
"chatgpt-ads": {
"command": "npx",
"args": ["-y", "@getmcpads/chatgpt-ads-mcp-server"],
"env": {
"OPENAI_ADS_API_KEY": "your-advertiser-api-key",
"OPENAI_ADS_ACCOUNT_ID": "adacct_your_account"
}
}
}
}Run npm run doctor to check the configuration without contacting ChatGPT Ads, then call openai_ads_get_account first.
Managed connection. Use ChatGPT Ads with hosted getmcpads. Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.
Configuration
Provide these environment variables through the client's secret configuration:
Variable | Purpose |
| Required. An Advertiser API key created on the Settings page of Ads Manager. Each key is scoped to one ad account. This is not an OpenAI Platform API key. |
| Required. The |
| Defaults to |
| Defaults to |
You need an ad account in Ads Manager and an Advertiser API key, as described in OpenAI's Advertiser API overview. Some features are enabled per account: the Bulk API is in limited preview, and API partners need pixel management and conversion-optimized bidding enabled for each client account, as described in API Partner Setup. The server returns the native access error when a feature is not enabled. API use is governed by OpenAI's Advertising Terms, which require you to keep API keys confidential.
This package reads a key from the environment. It runs no browser sign-in and writes nothing to disk. To rotate the key, create a new one in Ads Manager, update the variable and restart the server.
Safety and coverage
Writes preview by default. A call without confirm returns the change, the native state it was checked against and a confirmationToken. After the person approves the exact preview, repeat the identical call with confirm: true and that token. Use one requestId UUID per logical change; creations send it as the native Idempotency-Key, which OpenAI uses to avoid creating a duplicate when the same creation is sent again.
Before applying, the server reads the native state again and refuses the write if it changed since the preview. After applying, it reads campaigns, ad groups, ads and feed products back and reports whether the change is confirmed.
Campaigns, ad groups and ads are created paused. Activation is refused unless OPENAI_ADS_ENABLE_ACTIVATION=true, and previews that can start delivery carry activationMaySpend: true.
A write whose outcome is uncertain is recorded as UNKNOWN and never resubmitted. Read the receipt with openai_ads_get_mutation and the native state before deciding anything else. Previews and receipts live in memory and a restart forgets them.
Account checks run before every request. Unknown arguments are rejected, and nested request bodies are validated against the pinned native schemas.
Requests go only to api.ads.openai.com with a 30 second timeout and an 8 MiB response bound. Redirects are refused. The key is removed from any provider text, and only validation errors return native messages. The API allows 600 requests per minute per endpoint and 1,200 overall; a throttled request returns RATE_LIMITED without a retry.
Budgets and bids use integer micros of the account currency (1,000,000 is one unit). Reported spend, CPC and CPM use major units, CTR and conversion rates are fractions, and missing values stay null. Product feed prices use minor units (7999 is USD 79.99).
This server exposes a reviewed subset of the API. It leaves out API key provisioning, billing and spend limit changes, account administration, partner account creation, custom audience creation and membership uploads, lead sync webhooks and SFTP credentials. New upstream endpoints are not exposed automatically.
Use tools/list or server-card.json for exact schemas, openai_ads_get_write_schema for nested request fields, and the official API reference for provider details.
Hosted option
getmcpads for ChatGPT Ads manages the hosted connection and account selection. Hosted and source releases can differ. Contact: hello@getmcpads.com.
Development
npm run typecheck
npm run lint
npm run build
npm test
npm run catalogAll tests run offline with synthetic responses. No live account is read or changed. To refresh the pinned schemas, save the official OpenAPI document and run node scripts/generate-contracts.mjs <path> <date>.
Tools
Every tool is listed below. See server-card.json for complete parameter and output schemas. Every tool takes adAccountId, the account in OPENAI_ADS_ACCOUNT_ID.
Tool | Purpose |
| Read the account's name, currency, time zone, status and brand review, and verify that the key belongs to it. |
| List one page of campaigns. |
| Read one campaign with its budget, schedule and targeting. |
| List one page of the ad groups of a campaign. |
| Read one ad group with its bidding, context hints and product set. |
| List one page of the ads of an ad group, with creative metadata and review status. |
| Read one ad with its creative and review status. |
| List chat card creatives with their file IDs and signed image links, refreshing expired links. |
| Read performance by account, campaign, ad group or ad, with one optional country, device or platform breakdown and attribution settings. |
| Search country, region and market location IDs for geographic targeting. |
| List recorded changes to campaigns, ad groups and ads. |
| Read the account's spend limit windows. |
| Read the landing page crawl evidence for an ad's submitted version. |
| List conversion event settings, the goals a campaign can use. |
| List conversion pixels and connected pixel IDs. |
| List recent sampled conversion events, to check that a pixel or server integration sends data. |
| Read attributed conversion totals or daily values, optionally by country or device. |
| List product feeds, optionally with product counts. |
| List recent product feed uploads and their results. |
| Read a feed's display and organic-listing settings. |
| List feed products that match ad group product filters. |
| List custom audiences. |
| Read one custom audience and its matched count. |
| List the accepted operations of a custom audience. |
| Read the state of one custom audience operation. |
| Read the status of a Bulk API job. |
| Read one page of a Bulk API job's operation outcomes. |
| Read the pinned native request definitions, upload and bulk limits, and the exclusions. |
| Read the account, conversion settings and feeds before proposing a campaign, with the supported bid combinations. |
| Read a write preview or receipt held by this server process. |
Disabled by default. Calls preview unless explicitly confirmed. Check the configuration and exact schema before use.
Tool | Purpose |
| Create a paused campaign with its objective, budget, schedule and targeting. |
| Update campaign settings such as budget, schedule or targeting. |
| Pause a campaign. |
| Activate a campaign. Can spend budget; requires |
| Archive a campaign. |
| Create a paused ad group with its bidding, context hints and product set. |
| Update ad group settings such as bidding or context hints. |
| Pause an ad group. |
| Activate an ad group. Can spend budget; requires |
| Archive an ad group. |
| Create a paused ad with a chat card or product template creative, which enters review. |
| Update an ad's name or creative. A creative edit starts a new review. |
| Pause an ad. |
| Activate an ad. Can spend budget; requires |
| Archive an ad. |
| Create a temporary preview of an existing ad. |
| Rename a campaign. The name is the only field that changes. |
| Rename an ad group. The name is the only field that changes. |
| Rename an ad. The name is the only field that changes. |
| Upload PNG, JPEG or WebP bytes of at least 640 x 640 and return a file ID for a chat card. |
| Have OpenAI import a public HTTPS image and return a file ID. |
| Create a conversion event setting for a standard or custom event. |
| Create a conversion pixel. |
| Create a product feed. |
| Update a feed's display name and organic-listing settings. |
| Update the title, price or availability of up to 500 existing product variants. |
| Archive a product feed. |
| Submit a Bulk API job of up to 1,000 operations, validation only by default. |
Resource | Content |
| Account scope, write flow, units, rate limits, supported metrics, levels, breakdowns and attribution options. |
License
Apache License 2.0. See NOTICE.
More from getmcpads
Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads
Maintained by the getmcpads team at getmcpads. Questions: hello@getmcpads.com.
Available Tools
30 toolsopenai_ads_get_accountopenai ads get accountARead-onlyIdempotent
Read the configured ChatGPT Ads account: name, currency, time zone, status and brand review. Also verifies that the API key belongs to OPENAI_ADS_ACCOUNT_ID. Run it first.
Inputs: adAccountId (required). Returns: result
openai_ads_get_adopenai ads get adARead-onlyIdempotent
Read one ad with its creative and review status. No preview or change is requested.
Inputs: adId (required), adAccountId (required), include. Returns: result
openai_ads_get_ad_groupopenai ads get ad groupARead-onlyIdempotent
Read one ad group with its native bidding, context hints and product set.
Inputs: adGroupId (required), adAccountId (required), include. Returns: result
openai_ads_get_ad_groupsopenai ads get ad groupsARead-onlyIdempotent
List one page of ad groups in a campaign. Native ad group IDs start with adgrp_. Follow last_id only when has_more is true.
Inputs: campaignId (required), adAccountId (required), name, after, +4 more. Returns: result
openai_ads_get_adsopenai ads get adsARead-onlyIdempotent
List one page of ads in an ad group with native creative metadata and review status. Follow last_id only when has_more is true.
Inputs: adGroupId (required), adAccountId (required), name, after, +4 more. Returns: result
openai_ads_get_audience_operationopenai ads get audience operationARead-onlyIdempotent
Read the lifecycle state of one custom audience operation. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), operation_id (required), custom_audience_id (required). Returns: result
openai_ads_get_audience_operationsopenai ads get audience operationsBRead-onlyIdempotent
List the accepted operations of a custom audience. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), custom_audience_id (required), query. Returns: result
openai_ads_get_audit_logsopenai ads get audit logsARead-onlyIdempotent
List recorded changes to the account's campaigns, ad groups and ads, optionally filtered by entity, actor or time. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_bulk_jobopenai ads get bulk jobARead-onlyIdempotent
Read one Bulk API job (limited preview, enabled per account). Only completed, partially_failed and failed are terminal. A completed job still requires reading every operation result and the native entities.
Inputs: jobId (required), adAccountId (required). Returns: result
openai_ads_get_bulk_job_operationsopenai ads get bulk job operationsARead-onlyIdempotent
Read one page of Bulk API operation outcomes: created, updated, validated, failed or skipped. Pass the last operation_id as after only when has_more is true. A partial failure never rolls back earlier operations; do not resubmit an uncertain job.
Inputs: jobId (required), adAccountId (required), query. Returns: result
openai_ads_get_campaignopenai ads get campaignBRead-onlyIdempotent
Read one campaign with its native status, budget, schedule and targeting.
Inputs: campaignId (required), adAccountId (required), include. Returns: result
openai_ads_get_campaignsopenai ads get campaignsARead-onlyIdempotent
List one page of campaigns in the account. Follow last_id only when has_more is true. Budget amounts use integer account-currency micros.
Inputs: adAccountId (required), name, after, limit, +3 more. Returns: result
openai_ads_get_conversion_eventsopenai ads get conversion eventsARead-onlyIdempotent
List recent sampled conversion events, for checking that a pixel or server integration sends data. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_conversion_insightsopenai ads get conversion insightsARead-onlyIdempotent
Read attributed conversion totals or daily values, optionally by country or device and with event details. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: body (required), adAccountId (required). Returns: result
openai_ads_get_conversion_pixelsopenai ads get conversion pixelsBRead-onlyIdempotent
List the account's conversion pixels and connected pixel IDs. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_conversion_settingsopenai ads get conversion settingsARead-onlyIdempotent
List the account's conversion event settings, the goals a campaign can use. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_custom_audienceopenai ads get custom audienceARead-onlyIdempotent
Read one custom audience and its matched count. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), custom_audience_id (required), query. Returns: result
openai_ads_get_custom_audiencesopenai ads get custom audiencesBRead-onlyIdempotent
List the account's custom audiences. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_feed_productsopenai ads get feed productsBRead-onlyIdempotent
List products in a feed that match ad group product filters. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: body (required), feed_id (required), adAccountId (required). Returns: result
openai_ads_get_feedsopenai ads get feedsBRead-onlyIdempotent
List the account's product feeds, optionally with product counts. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_feed_settingsopenai ads get feed settingsARead-onlyIdempotent
Read a feed's display and organic-listing settings. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: feed_id (required), adAccountId (required). Returns: result
openai_ads_get_feed_uploadsopenai ads get feed uploadsARead-onlyIdempotent
List recent product feed uploads and their processing results. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
openai_ads_get_insightsopenai ads get insightsARead-onlyIdempotent
Read performance by account, campaign, ad group or ad over inclusive account-local dates. One optional country, device or platform breakdown supports delivery metrics only; use openai_ads_get_conversion_insights for conversions by country or device. Attribution defaults to 30-day click, 1-day view and ad_event_time. CTR and CVR are fractions; money uses major units of the account currency. Pages are followed up to maxRows and truncation is explicit.
Inputs: since (required), until (required), adAccountId (required), level, +5 more. Returns: result
openai_ads_get_landing_page_crawlopenai ads get landing page crawlARead-onlyIdempotent
Read the saved landing page crawl evidence for an ad's submitted version. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: ad_id (required), adAccountId (required). Returns: result
openai_ads_get_mutationopenai ads get mutationARead-onlyIdempotent
Read a write preview or receipt held by this server process: its state, the native state it was approved against and the result. Receipts live in memory and a restart forgets them. Never resubmit a write whose state is UNKNOWN or APPLYING.
Inputs: mutationId (required), adAccountId (required). Returns: result
openai_ads_get_spend_limitsopenai ads get spend limitsARead-onlyIdempotent
Read the account's spend limit windows and daily recurrence rules. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required). Returns: result
openai_ads_get_write_contextopenai ads get write contextARead-onlyIdempotent
Read the account, its conversion settings and its product feeds before proposing a campaign. Lists the native objective, billing and bid strategy combinations and the missing prerequisites. It grants no eligibility and creates nothing.
Inputs: adAccountId (required). Returns: result
openai_ads_get_write_schemaopenai ads get write schemaARead-onlyIdempotent
Read the pinned native request definitions, paths and parameters of every operation, the upload and bulk limits, and what this server leaves out. Schema support does not imply that the account is eligible for a feature.
Inputs: adAccountId (required), toolName. Returns: result
openai_ads_list_ad_creativesopenai ads list ad creativesARead-onlyIdempotent
List chat card creatives of the account or of one ad group, 20 ads per page, or read up to 60 exact adIds. Each item has the native file_id, signed image_url, title, body, destination and review status. An expired image link is refreshed with one ad read. Follow nextCursor when hasMore.
Inputs: adAccountId (required), adIds, after, limit, +1 more. Returns: result
openai_ads_search_locationsopenai ads search locationsARead-onlyIdempotent
Search country, region and market location IDs for campaign geographic targeting. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.
Inputs: adAccountId (required), query. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Each tool targets a distinct resource or report (campaigns vs ad groups vs ads vs feeds vs audiences vs bulk jobs), and the insights vs conversion_insights split is explicitly documented. The main friction is the large set of near-neighbor tools (get_custom_audiences / get_custom_audience / get_audience_operations / get_audience_operation, and get_write_schema / get_write_context / get_mutation) where an agent must read carefully, plus get_* names that sometimes list and sometimes read one entity.
All names share the openai_ads_ prefix and a verb_noun shape, so the set is predictable. However the verb usage is loose: get_ is used for both list operations (get_campaigns, get_ads, get_feeds) and single-entity reads, while list_ and search_ appear only once each, which weakens the pattern's signal.
30 tools is heavy for a single MCP server and sits above the comfortable 15-tool band, even though the domain (campaigns, creatives, conversions, feeds, audiences, audit, bulk) is genuinely broad. Several read-only sub-resources (audience operations, feed uploads, feed settings, landing page crawl) could reasonably be folded into parent tools to slim the surface.
Read coverage is deep and coherent across the ad lifecycle, including diagnostics and bulk job result inspection. But the surface is read-heavy: get_write_schema, get_write_context and get_mutation reference write previews and receipts while no tool actually submits a mutation, leaving a dangling step in the advertised lifecycle and no create/update/delete operations.
Maintenance
Related MCP Connectors
OpenAI Ads MCP for ChatGPT Ads campaigns, creatives, audiences, insights, and conversions.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Analyze, edit and launch Meta (Facebook and Instagram) ads from Claude, ChatGPT, Cursor or Codex. Query insights and campaign health, change budgets, bids, status and targeting with undo, bulk-launch many ads across campaigns and ad sets from a live ad's settings, and duplicate by post to keep social proof. Choose per ad account what the agent may do and what waits in the Agent Inbox for approval. Requires a paid Ads Uploader account with MCP access.
Related MCP Servers
- 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
- AlicenseBqualityDmaintenanceTyped MCP server for OpenAI Ads and ChatGPT Ads via the Advertiser API. Supports account, campaign, ad group, ad, creative, audience, insight, and conversion tools with readonly mode and guarded writes.124MIT
- AlicenseBqualityCmaintenanceEnables managing ChatGPT Advertiser campaigns from MCP-capable agents, including campaign creation, creative uploads, audience management, conversions setup, and insights retrieval.8938 npmMIT
- AlicenseBqualityCmaintenanceEnables AI assistants to read a ChatGPT Ads account — account summaries, performance insights, campaigns, ad groups, ads, product feeds and conversion setup — and, when writes are explicitly enabled, create or update campaigns, budgets and creatives with dry-run previews and before/after diffs.151MIT