Skip to main content
Glama
ChatGPT Ads MCP server

ChatGPT Ads MCP server

by get-mcp-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.

Release CI License: Apache 2.0 Node

Watch the film · What's new · Install · Tool reference · Try hosted getmcpads

Watch the getmcpads film: every ad account in one conversation with your AI assistant

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.2: Maintainer metadata update · November 8, 2026

  • List the getmcpads team as maintainer in package.json, the README and SOURCE_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

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.

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

Variable

Purpose

OPENAI_ADS_API_KEY

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.

OPENAI_ADS_ACCOUNT_ID

Required. The adacct_ ID of the account the key belongs to. Every other account ID is refused, and the first request checks that the key matches.

OPENAI_ADS_ENABLE_WRITES

Defaults to false. Only the exact value true registers the write tools.

OPENAI_ADS_ENABLE_ACTIVATION

Defaults to false. true allows activation and changes to status: "active", which can start delivery and spend budget. Requires writes.

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.

Tool

Purpose

openai_ads_get_account

Read the account's name, currency, time zone, status and brand review, and verify that the key belongs to it.

openai_ads_get_campaigns

List one page of campaigns.

openai_ads_get_campaign

Read one campaign with its budget, schedule and targeting.

openai_ads_get_ad_groups

List one page of the ad groups of a campaign.

openai_ads_get_ad_group

Read one ad group with its bidding, context hints and product set.

openai_ads_get_ads

List one page of the ads of an ad group, with creative metadata and review status.

openai_ads_get_ad

Read one ad with its creative and review status.

openai_ads_list_ad_creatives

List chat card creatives with their file IDs and signed image links, refreshing expired links.

openai_ads_get_insights

Read performance by account, campaign, ad group or ad, with one optional country, device or platform breakdown and attribution settings.

openai_ads_search_locations

Search country, region and market location IDs for geographic targeting.

openai_ads_get_audit_logs

List recorded changes to campaigns, ad groups and ads.

openai_ads_get_spend_limits

Read the account's spend limit windows.

openai_ads_get_landing_page_crawl

Read the landing page crawl evidence for an ad's submitted version.

openai_ads_get_conversion_settings

List conversion event settings, the goals a campaign can use.

openai_ads_get_conversion_pixels

List conversion pixels and connected pixel IDs.

openai_ads_get_conversion_events

List recent sampled conversion events, to check that a pixel or server integration sends data.

openai_ads_get_conversion_insights

Read attributed conversion totals or daily values, optionally by country or device.

openai_ads_get_feeds

List product feeds, optionally with product counts.

openai_ads_get_feed_uploads

List recent product feed uploads and their results.

openai_ads_get_feed_settings

Read a feed's display and organic-listing settings.

openai_ads_get_feed_products

List feed products that match ad group product filters.

openai_ads_get_custom_audiences

List custom audiences.

openai_ads_get_custom_audience

Read one custom audience and its matched count.

openai_ads_get_audience_operations

List the accepted operations of a custom audience.

openai_ads_get_audience_operation

Read the state of one custom audience operation.

openai_ads_get_bulk_job

Read the status of a Bulk API job.

openai_ads_get_bulk_job_operations

Read one page of a Bulk API job's operation outcomes.

openai_ads_get_write_schema

Read the pinned native request definitions, upload and bulk limits, and the exclusions.

openai_ads_get_write_context

Read the account, conversion settings and feeds before proposing a campaign, with the supported bid combinations.

openai_ads_get_mutation

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

openai_ads_create_campaign

Create a paused campaign with its objective, budget, schedule and targeting.

openai_ads_update_campaign

Update campaign settings such as budget, schedule or targeting.

openai_ads_pause_campaign

Pause a campaign.

openai_ads_activate_campaign

Activate a campaign. Can spend budget; requires OPENAI_ADS_ENABLE_ACTIVATION.

openai_ads_archive_campaign

Archive a campaign.

openai_ads_create_ad_group

Create a paused ad group with its bidding, context hints and product set.

openai_ads_update_ad_group

Update ad group settings such as bidding or context hints.

openai_ads_pause_ad_group

Pause an ad group.

openai_ads_activate_ad_group

Activate an ad group. Can spend budget; requires OPENAI_ADS_ENABLE_ACTIVATION.

openai_ads_archive_ad_group

Archive an ad group.

openai_ads_create_ad

Create a paused ad with a chat card or product template creative, which enters review.

openai_ads_update_ad

Update an ad's name or creative. A creative edit starts a new review.

openai_ads_pause_ad

Pause an ad.

openai_ads_activate_ad

Activate an ad. Can spend budget; requires OPENAI_ADS_ENABLE_ACTIVATION.

openai_ads_archive_ad

Archive an ad.

openai_ads_create_ad_preview

Create a temporary preview of an existing ad.

openai_ads_rename_campaign

Rename a campaign. The name is the only field that changes.

openai_ads_rename_ad_group

Rename an ad group. The name is the only field that changes.

openai_ads_rename_ad

Rename an ad. The name is the only field that changes.

openai_ads_upload_image

Upload PNG, JPEG or WebP bytes of at least 640 x 640 and return a file ID for a chat card.

openai_ads_upload_image_url

Have OpenAI import a public HTTPS image and return a file ID.

openai_ads_create_conversion_setting

Create a conversion event setting for a standard or custom event.

openai_ads_create_conversion_pixel

Create a conversion pixel.

openai_ads_create_feed

Create a product feed.

openai_ads_update_feed_settings

Update a feed's display name and organic-listing settings.

openai_ads_update_feed_products

Update the title, price or availability of up to 500 existing product variants.

openai_ads_archive_feed

Archive a product feed.

openai_ads_submit_bulk_job

Submit a Bulk API job of up to 1,000 operations, validation only by default.

Resource

Content

openai-ads://guide

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 tools
openai_ads_get_accountopenai ads get accountA
Read-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 adA
Read-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 groupA
Read-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 groupsA
Read-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 adsA
Read-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 operationA
Read-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 operationsB
Read-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 logsA
Read-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 jobA
Read-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 operationsA
Read-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 campaignB
Read-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 campaignsA
Read-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 eventsA
Read-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 insightsA
Read-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 pixelsB
Read-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 settingsA
Read-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 audienceA
Read-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 audiencesB
Read-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 productsB
Read-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 feedsB
Read-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 settingsA
Read-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 uploadsA
Read-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 insightsA
Read-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 crawlA
Read-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 mutationA
Read-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 limitsA
Read-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 contextA
Read-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 schemaA
Read-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 creativesA
Read-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 locationsA
Read-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

    A3.5/5.0

    Scored across 30 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    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
      D
      maintenance
      Typed 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.
      12
      4
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables managing ChatGPT Advertiser campaigns from MCP-capable agents, including campaign creation, creative uploads, audience management, conversions setup, and insights retrieval.
      89
      38 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      15
      1
      MIT