ChatGPT Ads

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

Play the 45-second film

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.0: First standalone release · October 23, 2026

• Create the first standalone server for the ChatGPT Ads Advertiser API, ported from the hosted getmcpads gateway at revision 3e1c2c8.
• Expose 30 read tools, 28 write tools that are disabled by default, and one guide resource.
• Read the account, campaigns, ad groups, ads, chat card creatives, performance insights with country, device and platform breakdowns, conversion setup and insights, product feeds, custom audiences, audit logs, spend limits and Bulk API jobs.
• Pin the native request schemas to the public OpenAPI document (sha256 266e7e19), with a generator that refreshes them from a saved copy.
• Scope every call to the account in OPENAI_ADS_ACCOUNT_ID and verify on the first request that the API key belongs to it.
• Preview every write and apply only the exact saved preview after confirmation. Creations are paused, activation needs its own flag, and nothing is retried automatically.
• Send requests only to api.ads.openai.com, refuse redirects, bound response size and time, and redact the key from provider text.
• Require Node.js 22.23.4, 24.22.1, 26.12.1 or newer within each line, and warn on stderr when the runtime lacks the October 2026 security fixes.

Full changelog · All releases

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.

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.0 --depth 1 https://github.com/get-mcp-ads/chatgpt-ads-mcp-server.git
cd chatgpt-ads-mcp-server
npm ci
npm run build

Configure 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:

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 catalog

All 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.

30 read tools

28 write tools

Disabled by default. Calls preview unless explicitly confirmed. Check the configuration and exact schema before use.

1 resource

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 Emmanuel at getmcpads. Questions: hello@getmcpads.com.