ChatGPT Ads

宣传片展示的是使用示例数据的托管版 getmcpads。其 MCP Apps（包括创意素材库、提醒、Google Sheets 导出和批量投放）属于托管产品。本仓库提供独立的原生 API 工具。

30 个读取工具 · 28 个写入工具，默认禁用。

使用自己的 Advertiser API 密钥，并通过支持 stdio MCP 的客户端（例如 Claude Desktop、Claude Code 或 Cursor）在本地运行。请求会直接发送到 ChatGPT Ads API。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管版。

更新内容

v1.0.0：首个独立版本 · 2026 年 10 月 23 日

• 为 ChatGPT Ads Advertiser API 创建首个独立服务，该服务从托管版 getmcpads 网关的修订版 3e1c2c8 移植而来。
• 提供 30 个读取工具、28 个默认禁用的写入工具，以及一个指南资源。
• 读取账户、广告系列、广告组、广告、聊天卡片创意素材、按国家/地区、设备和平台细分的效果洞察、转化设置和洞察、产品 Feed、自定义受众、审计日志、支出限额及 Bulk API 作业。
• 将原生请求架构固定为公开 OpenAPI 文档（sha256 266e7e19），并提供生成器，可从保存的副本刷新架构。
• 将每次调用限定在 OPENAI_ADS_ACCOUNT_ID 指定的账户，并在首次请求时验证 API 密钥是否属于该账户。
• 预览所有写入操作，且仅在确认后应用确切保存的预览。创建操作默认暂停；激活需要单独的标记；不会自动重试任何操作。
• 仅向 api.ads.openai.com 发送请求，拒绝重定向，限制响应大小和耗时，并从提供方文本中删除密钥。
• 要求使用 Node.js 22.23.4、24.22.1、26.12.1 或各主版本线中更新的版本；如果运行时缺少 2026 年 10 月的安全修复，会在 stderr 上发出警告。

完整变更日志 · 所有版本

源同步信息：SOURCE_SYNC.md。

升级说明

需要 Node.js 22 版本线的 22.23.4 或更高版本、24 版本线的 24.22.1 或更高版本，或 26.12.1 或更高版本。这些版本包含 2026 年 10 月的安全修复；如果在较旧的运行时上启动，服务会在 stderr 上输出警告。CI 覆盖 Node 22、24 和 26。写入功能仍为可选功能，且需要明确确认。托管版创意素材集成和 MCP Apps UI 不在此版本范围内。

安装此版本

这是一个 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本；本文档后面未固定版本的 npx 示例会选择 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

配置 MCP 客户端，使其运行 node，并将 dist/cli.js 的绝对路径和下文所述的环境变量传入。使用 npm 包时，客户端配置如下：

{
  "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"
      }
    }
  }
}

运行 npm run doctor，在不联系 ChatGPT Ads 的情况下检查配置，然后先调用 openai_ads_get_account。

托管连接。 通过托管的 getmcpads 使用 ChatGPT Ads。连接你的账户，选择助手可以访问的数据，并使用托管的 MCP 连接。当前功能和方案请参阅网站。

配置

通过客户端的密钥配置提供以下环境变量：

变量	用途
OPENAI_ADS_API_KEY	必填。在 Ads Manager 的“Settings”页面创建的 Advertiser API 密钥。每个密钥仅适用于一个广告账户。这不是 OpenAI Platform API 密钥。
OPENAI_ADS_ACCOUNT_ID	必填。密钥所属账户的 adacct_ ID。其他所有账户 ID 都会被拒绝，且首次请求会检查密钥是否匹配。
OPENAI_ADS_ENABLE_WRITES	默认为 false。只有值恰为 true 时才会注册写入工具。
OPENAI_ADS_ENABLE_ACTIVATION	默认为 false。设为 true 后可启用，并将状态更改为 status: "active"，这可能会开始投放并消耗预算。需要启用写入功能。

你需要在 Ads Manager 中拥有广告账户和 Advertiser API 密钥，详情请参阅 OpenAI 的 Advertiser API 概述。部分功能需按账户启用：Bulk API 目前处于有限预览阶段；API 合作伙伴需要为每个客户端账户启用像素管理和转化优化出价，详情请参阅 API Partner Setup。如果某项功能未启用，服务会返回原生访问错误。API 的使用受 OpenAI 的广告条款约束，这些条款要求你对 API 密钥保密。

此软件包会从环境变量读取密钥，不会运行浏览器登录，也不会向磁盘写入任何内容。若要轮换密钥，请在 Ads Manager 中创建新密钥，更新变量并重启服务。

安全性与覆盖范围

默认情况下，写入操作会先预览。不带 confirm 的调用会返回变更内容、用于核对的原生状态以及 confirmationToken。用户批准确切的预览后，使用 confirm: true 和该令牌重复完全相同的调用。每项逻辑变更使用一个 requestId UUID；创建操作会将其作为原生 Idempotency-Key 发送，OpenAI 会据此避免重复提交相同的创建请求。 应用变更前，服务端会再次读取原生状态；如果状态自预览后发生变化，就会拒绝写入。应用后，服务端会重新读取广告系列、广告组、广告和商品 Feed 产品，并报告变更是否已确认。 广告系列、广告组和广告均以暂停状态创建。除非设置 OPENAI_ADS_ENABLE_ACTIVATION=true，否则会拒绝激活；可能开始投放的预览会标注 activationMaySpend: true。 结果不确定的写入会记录为 UNKNOWN，且绝不会重新提交。请使用 openai_ads_get_mutation 和原生状态读取回执，再决定下一步操作。预览和回执保存在内存中，重启后会丢失。 每次请求前都会执行账户检查。未知参数会被拒绝，嵌套请求正文会根据固定版本的原生架构进行验证。

请求仅发送到 api.ads.openai.com，超时时间为 30 秒，响应大小上限为 8 MiB。请求不允许重定向。密钥会从任何提供方文本中移除，只有验证错误会返回原生消息。API 每个端点每分钟允许 600 次请求，总计每分钟允许 1,200 次；触发限流的请求会返回 RATE_LIMITED，且不会重试。 预算和出价使用账户货币的整数微单位（1,000,000 微单位为 1 个单位）。报告中的支出、CPC 和 CPM 使用主要货币单位；CTR 和转化率使用小数表示；缺失值保持为 null。商品 Feed 价格使用次要货币单位（7999 表示 USD 79.99）。

此服务仅公开经过审核的 API 子集。不包含 API 密钥配置、账单和支出限额变更、账户管理、合作伙伴账户创建、自定义受众创建及成员上传、潜在客户同步 Webhook 和 SFTP 凭据。上游新增的端点不会自动公开。 确切架构请使用 tools/list 或查看 server-card.json；嵌套请求字段请使用 openai_ads_get_write_schema；提供方详情请参阅官方 API 参考。

托管选项

getmcpads for ChatGPT Ads 可管理托管连接和账户选择。 托管版本与源码版本可能有所不同。联系方式：[email protected]。

开发

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

所有测试均使用合成响应离线运行，不会读取或更改任何真实账户。若要刷新固定版本的架构，请保存官方 OpenAPI 文档，然后运行 node scripts/generate-contracts.mjs <path> <date>。

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。每个工具都需要 adAccountId，即 OPENAI_ADS_ACCOUNT_ID 中的账户。

30 个读取工具

| 工具 | 用途 | | --- | --- | | `openai_ads_get_account` | 读取账户名称、币种、时区、状态和品牌审核状态，并验证密钥是否属于该账户。 | | `openai_ads_get_campaigns` | 列出一页广告系列。 | | `openai_ads_get_campaign` | 读取一个广告系列及其预算、排期和定向设置。 | | `openai_ads_get_ad_groups` | 列出一个广告系列中的一页广告组。 | | `openai_ads_get_ad_group` | 读取一个广告组及其出价、上下文提示和商品集。 | | `openai_ads_get_ads` | 列出一个广告组中的一页广告，并显示创意元数据和审核状态。 | | `openai_ads_get_ad` | 读取一则广告及其创意和审核状态。 | | `openai_ads_list_ad_creatives` | 列出聊天卡片创意及其文件 ID 和签名图片链接，并刷新已过期的链接。 | | `openai_ads_get_insights` | 按账户、广告系列、广告组或广告读取效果数据，可选择按一个国家/地区、设备或平台维度细分，并设置归因选项。 | | `openai_ads_search_locations` | 搜索地理定向所用的国家/地区、区域和市场位置 ID。 | | `openai_ads_get_audit_logs` | 列出广告系列、广告组和广告的记录变更。 | | `openai_ads_get_spend_limits` | 读取账户的支出限额窗口。 | | `openai_ads_get_landing_page_crawl` | 读取广告已提交版本的着陆页抓取证据。 | | `openai_ads_get_conversion_settings` | 列出转化事件设置，即广告系列可使用的目标。 | | `openai_ads_get_conversion_pixels` | 列出转化像素和关联的像素 ID。 | | `openai_ads_get_conversion_events` | 列出近期抽样转化事件，用于检查像素或服务器集成是否发送数据。 | | `openai_ads_get_conversion_insights` | 读取归因转化总数或每日数据，可选择按国家/地区或设备细分。 | | `openai_ads_get_feeds` | 列出商品 Feed，可选择显示商品数量。 | | `openai_ads_get_feed_uploads` | 列出近期商品 Feed 上传记录及其结果。 | | `openai_ads_get_feed_settings` | 读取 Feed 的展示和自然列表设置。 | | `openai_ads_get_feed_products` | 列出符合广告组商品筛选条件的 Feed 商品。 | | `openai_ads_get_custom_audiences` | 列出自定义受众。 | | `openai_ads_get_custom_audience` | 读取一个自定义受众及其匹配数量。 | | `openai_ads_get_audience_operations` | 列出自定义受众已接受的操作。 | | `openai_ads_get_audience_operation` | 读取一个自定义受众操作的状态。 | | `openai_ads_get_bulk_job` | 读取 Bulk API 作业的状态。 | | `openai_ads_get_bulk_job_operations` | 读取 Bulk API 作业中一页操作的结果。 | | `openai_ads_get_write_schema` | 读取固定版本的原生请求定义、上传和批量操作限制，以及排除项。 | | `openai_ads_get_write_context` | 在拟定广告系列前读取账户、转化设置和 Feed，以及受支持的出价组合。 | | `openai_ads_get_mutation` | 读取此服务进程保留的写入预览或回执。 |

28 个写入工具

默认禁用。除非明确确认，否则调用仅生成预览。使用前请检查配置和确切的架构。

工具	用途
openai_ads_create_campaign	创建包含目标、预算、排期和定向设置的暂停状态广告系列。
openai_ads_update_campaign	更新广告系列设置，例如预算、排期或定向。
openai_ads_pause_campaign	暂停广告系列。
openai_ads_activate_campaign	启用广告系列。可能会产生预算支出；需要设置 OPENAI_ADS_ENABLE_ACTIVATION。
openai_ads_archive_campaign	将广告系列归档。
openai_ads_create_ad_group	创建包含出价、上下文提示和商品集的暂停状态广告组。
openai_ads_update_ad_group	更新广告组设置，例如出价或上下文提示。
openai_ads_pause_ad_group	暂停广告组。
openai_ads_activate_ad_group	启用广告组。可能会产生预算支出；需要设置 OPENAI_ADS_ENABLE_ACTIVATION。
openai_ads_archive_ad_group	将广告组归档。
openai_ads_create_ad	创建包含聊天卡片或商品模板素材的暂停状态广告，并提交审核。
openai_ads_update_ad	更新广告名称或素材。编辑素材会重新启动审核。
openai_ads_pause_ad	暂停广告。
openai_ads_activate_ad	启用广告。可能会产生预算支出；需要设置 OPENAI_ADS_ENABLE_ACTIVATION。
openai_ads_archive_ad	将广告归档。
openai_ads_create_ad_preview	为现有广告创建临时预览。
openai_ads_rename_campaign	重命名广告系列。名称是唯一会更改的字段。
openai_ads_rename_ad_group	重命名广告组。名称是唯一会更改的字段。
openai_ads_rename_ad	重命名广告。名称是唯一会更改的字段。
openai_ads_upload_image	上传至少为 640 x 640 的 PNG、JPEG 或 WebP 字节，并返回聊天卡片所需的文件 ID。
openai_ads_upload_image_url	让 OpenAI 导入公开的 HTTPS 图片并返回文件 ID。
openai_ads_create_conversion_setting	为标准事件或自定义事件创建转化事件设置。
openai_ads_create_conversion_pixel	创建转化像素。
openai_ads_create_feed	创建商品 Feed。
openai_ads_update_feed_settings	更新 Feed 的显示名称和自然列表设置。
openai_ads_update_feed_products	更新最多 500 个现有商品变体的标题、价格或库存情况。
openai_ads_archive_feed	将商品 Feed 归档。
openai_ads_submit_bulk_job	提交最多包含 1,000 项操作的 Bulk API 作业，默认仅进行验证。

1 个资源

资源	内容
openai-ads://guide	账户范围、写入流程、单位、速率限制、支持的指标、层级、细分维度和归因选项。

许可证

Apache License 2.0。请参阅 NOTICE。

更多 getmcpads 项目

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。问题请联系：[email protected]。