OpenAI Ads MCP

openai-ads-mcp

Trakkr 跟踪完整的 AI 可见性漏斗，包括自然流量和付费流量。这是其付费侧的开源配套项目。

openai-ads-mcp 是一个面向 OpenAI Ads、ChatGPT Ads 和 OpenAI Advertiser API 的类型化模型上下文协议服务。它让 Claude、Cursor、Codex、VS Code 和其他 MCP 客户端能够检查广告账户、查看效果洞察、创建暂停状态的广告系列、上传创意素材、管理受众并发送转化事件。

人们经常搜索 ChatGPT Ads MCP，因为这些广告会出现在 ChatGPT 中。该软件包保留 OpenAI Ads MCP 这个名称，因为 ChatGPT Ads 通过 OpenAI Ads、Ads Manager 和 OpenAI Advertiser API 管理。

当前公开版本：0.1.7。

它提供两种运行时，工具名称、参数、默认值、安全模型和随附的 OpenAPI 参考文档均相同：

运行时	推荐安装方式	软件包路径
Python	uvx openai-ads-mcp	python/
Node	npx -y openai-ads-mcp	typescript/

目标很简单：让 AI 助手能够使用 OpenAI Ads，同时避免意外触发广告支出。

安装

使用 uvx 安装 Python 版：

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

使用 pip 安装 Python 版：

python -m pip install openai-ads-mcp
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
openai-ads-mcp

使用 npx 安装 Node 版：

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

使用 npm 安装 Node 版：

npm install -g openai-ads-mcp
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
openai-ads-mcp

从这个 monorepo 进行本地开发：

cd services/openai-ads-mcp/python
python -m pip install -e .
python -m openai_ads_mcp

cd ../typescript
npm install
npm run build
node dist/index.js

配置

在 OpenAI Ads Manager 中创建 Ads API 密钥，然后将其作为环境变量传入。

export OPENAI_ADS_API_KEY="..."

建议首次连接时：

export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

或者使用 Node：

export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

只读模式会隐藏所有写入工具。它们不会出现在 tools/list 中，也无法调用。确认账户并检查数据后，取消设置 OPENAI_ADS_MCP_READONLY 即可启用写入功能。

可选环境变量：

变量	用途
OPENAI_ADS_API_KEY	https://api.ads.openai.com/v1 所需的 bearer 密钥。
OPENAI_ADS_API_BASE_URL	可选的 HTTPS 覆盖值，用于测试或代理。
OPENAI_ADS_MCP_READONLY	设置为 1 或 true 时，仅注册读取工具。
OPENAI_ADS_BUDGET_CEILING_USD	可选的预算上限保护。默认值为 100。

发现元数据

此仓库包含供官方 MCP Registry 和下游 MCP 目录使用的 server.json。规范注册名称为：

io.github.trakkr-aisearch/openai-ads-mcp

Node 软件包包含匹配的 mcpName，Python 软件包 README 则包含匹配的 mcp-name 标记，用于 PyPI 所有权验证。

注册表元数据还公布了托管的只读 Streamable HTTP 端点：

https://openai-ads-mcp.trakkr.ai/mcp

此托管端点用于发现和只读使用。它不会存储或使用 Trakkr 所有的 OpenAI Ads API 密钥。 此托管端点允许匿名调用 initialize 和 tools/list；调用 Ads API 工具时，调用方必须发送 X-OpenAI-Ads-API-Key。

MCP 客户端示例

Claude Code，Python 运行时

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- uvx openai-ads-mcp

Claude Code，Node 运行时

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- npx -y openai-ads-mcp

Cursor 或 Claude Desktop

{
  "mcpServers": {
    "openai-ads": {
      "command": "uvx",
      "args": ["openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your_ads_key_here",
        "OPENAI_ADS_MCP_READONLY": "1"
      }
    }
  }
}

Node 运行时请使用 "command": "npx" 和 "args": ["-y", "openai-ads-mcp"]。

Codex CLI

[mcp_servers.openai_ads]
command = "uvx"
args = ["openai-ads-mcp"]
env = { OPENAI_ADS_API_KEY = "your_ads_key_here", OPENAI_ADS_MCP_READONLY = "1" }

MCP Registry

兼容注册表的客户端应按名称发现此服务：

io.github.trakkr-aisearch/openai-ads-mcp

注册表元数据列出了 npm、PyPI 和托管的 Streamable HTTP 端点。发现服务时，托管端点无需 API 密钥；但调用 Ads API 工具时，必须提供 X-OpenAI-Ads-API-Key。

Docker

此仓库包含用于部署托管 Streamable HTTP 的生产环境 Dockerfile：

docker build -t openai-ads-mcp .
docker run --rm -p 8080:8080 \
  -e OPENAI_ADS_MCP_HOSTED_PUBLIC=1 \
  -e OPENAI_ADS_MCP_TELEMETRY_SALT="local-test-salt" \
  openai-ads-mcp

范围较窄的 typescript/Dockerfile 由 Cloud Run 部署脚本使用。本地 stdio 使用时，建议使用 uvx openai-ads-mcp 或 npx -y openai-ads-mcp。

流式 HTTP

Node 运行时还可通过流式 HTTP 提供 MCP 服务，用于托管部署或团队部署：

export OPENAI_ADS_MCP_HTTP_TOKEN="choose_a_long_random_token"
export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp --http

默认值：

• URL：本地为 http://127.0.0.1:8080/mcp，通过代理访问时为 https://your-host/mcp。
• 健康检查：GET /healthz、GET /health 和 GET /ready。
• 远程模式会强制将 OPENAI_ADS_MCP_READONLY=1，除非设置了 OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1。
• OPENAI_ADS_MCP_HTTP_TOKEN 使用 Authorization: Bearer <token> 保护 MCP 端点。
• 客户端可在每个请求中发送 X-OpenAI-Ads-API-Key，也可以由服务使用服务端的 OPENAI_ADS_API_KEY。

常用托管环境变量：

变量	用途
PORT 或 OPENAI_ADS_MCP_HTTP_PORT	HTTP 端口。默认值为 8080。
OPENAI_ADS_MCP_HTTP_PATH	MCP 路径。默认值为 /mcp。
OPENAI_ADS_MCP_HEALTH_PATH	健康检查路径。默认值为 /healthz。
OPENAI_ADS_MCP_HTTP_TOKEN	可选的 Bearer 令牌，托管客户端必须提供。
OPENAI_ADS_MCP_HTTP_ALLOW_WRITES	仅当你希望通过 HTTP 暴露写入工具时，才设置为 1。
OPENAI_ADS_MCP_HTTP_CORS_ORIGIN	可选的 CORS 来源。默认值为 *。

对于公开托管的端点，请保持禁用写入，并要求用户在每个请求中提供自己的 Ads API 密钥。不要在浏览器可见的配置中放入共享 Ads API 密钥。

公开托管模式

对于公开发现端点，请使用：

export OPENAI_ADS_MCP_HOSTED_PUBLIC=1
export OPENAI_ADS_MCP_TELEMETRY_SALT="long_random_value"
npx -y openai-ads-mcp --http

公开托管模式：

• 强制启用只读模式
• 如果 OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1，则拒绝启动
• 如果存在 OPENAI_ADS_API_KEY，则拒绝启动
• 拒绝 X-OpenAI-Ads-API-Base-Url
• 允许匿名执行 initialize 和 tools/list
• Ads API 工具调用需要 X-OpenAI-Ads-API-Key
• 对发现和工具调用进行速率限制
• 仅记录经过脱敏的摘要、哈希值、计数、状态、延迟和客户端元数据

生产环境运行手册位于 HOSTED_DEPLOY.md。

工具范围

Python 和 Node 运行时暴露相同的 27 个工具。

分组	工具
账户	get_account
广告系列	list_campaigns、get_campaign、create_campaign、update_campaign、set_campaign_state
广告组	list_ad_groups、get_ad_group、create_ad_group、update_ad_group、set_ad_group_state
广告	list_ads、get_ad、upload_creative、create_ad、update_ad、set_ad_state
洞察	get_insights
受众	list_audiences、get_audience、search_geo、manage_audience
转化	manage_conversions、send_conversions
辅助工具	build_campaign、draft_context_hints、bulk_ab_test_hints

高频工具

工具	功能
get_account	获取广告账户，并确认 API 密钥可用。
get_insights	读取账户、广告系列、广告组或广告的洞察数据，支持字段、筛选条件、排序、细分和游标分页。
create_campaign	创建一个已暂停的广告系列，并设置受保护的总预算上限；包括仅设置一个事件的转化优化广告系列。
upload_creative	上传图片 URL 或本地图片文件，并返回 file_id。
create_ad	创建一条已暂停的广告。chat_card 需要 target_url 和 file_id。
build_campaign	在受保护的工作流中创建一个已暂停的广告系列、一个已暂停的广告组和多条已暂停的广告。
draft_context_hints	以确定性方式起草符合 API 格式的 context_hints，不会隐式调用大模型。
send_conversions	在本地验证后，将转化事件发送到 https://bzr.openai.com/v1/events?pid=...，并可选择使用 validate_only。支持 obref 和移动应用生命周期事件。

get_insights 接受当前带标签的时间范围格式，例如：

{"type":"unix_range","start":1764547200,"end":1765152000}

为向后兼容，旧的嵌套格式也会经过规范化处理。

如需优化转化，请向 create_campaign 传入 bidding_type="conversions" 和且仅一个 conversion_event_setting_ids 值。广告系列不能使用商品 Feed 模式，子广告组必须按点击计费。build_campaign 也支持此路径，可通过其单数形式的辅助参数 conversion_event_setting_id 使用。尽管 OpenAI 按点击向子广告组收费，但出价仍是 CPA 输入值。

OpenAI 的 Bulk API 仍处于有限预览阶段，不作为通用 MCP 工具提供。支持商品 Feed 广告系列对象，但 Feed 连接和目录上传仍需在 Ads Manager 中完成，或通过 OpenAI 支持的 SFTP 流程完成。

安全模型

此服务可能影响实际广告支出，因此默认设置有意采取谨慎策略。

1. 创建工具默认将对象设为暂停状态。build_campaign 创建的所有对象都会暂停。
2. 激活操作由独立工具执行：set_campaign_state、set_ad_group_state 和 set_ad_state。
3. 设置预算的路径会强制执行 OPENAI_ADS_BUDGET_CEILING_USD，默认值为 100。
4. 如需超出上限，请传入 confirm_budget=True。
5. OPENAI_ADS_MCP_READONLY=1 会完全隐藏所有写入工具。
6. 每次调用最多验证 1000 个转化事件；时间戳不得早于 7 天前，也不得晚于未来 10 分钟。
7. 使用 validate_only=true 可验证转化批次，但不摄取数据。
8. 此服务绝不会记录 API 密钥或转化用户数据。

每个工具都设置了 MCP 注解。读取工具使用 readOnlyHint。写入工具使用 readOnlyHint=false。标记为破坏性操作且面向开放世界的激活和预算变更工具，会提示宿主在运行前征求确认。

操作示例

首先，安全地连接：

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

向助手提问：

Call get_account and list_campaigns. Confirm the Ads key works and show me what already exists.

然后在非只读模式下重启，并创建一个已暂停的广告系列：

Use draft_context_hints for "AI visibility monitoring software" aimed at growth teams with comparison intent.

Then call build_campaign with:
- name: "AI visibility category test"
- budget_usd: 50
- ad_group: name "Growth teams", billing_event "click", max_bid_usd 1.25, context_hints from the draft
- ads: two chat_card variants using my uploaded file_id

Do not activate anything.

检查返回的广告系列、广告组、广告、预算、定向设置和审核状态。准备好上线后，明确激活每一层：

Call set_campaign_state with state="activate".
Call set_ad_group_state with state="activate".
Call set_ad_state for the approved ad with state="activate".

自然流量这一面

付费广告位回答的是：你在哪里购买了关注度？

Trakkr 回答的是：你的品牌在 ChatGPT、Perplexity、Gemini、Claude、Google AI Overviews、Reddit 上的自然曝光情况如何？涵盖引用、排名、竞争对手、情感倾向、提示词、报告和行动。

在 trakkr.ai 追踪自然流量。想将 AI 搜索缺口转化为内容简报时，可使用 Trakkr 生成器 trakkr.ai/create。

此 MCP 还提供一项可选资源：

openai-ads://trakkr-visibility

它会返回一份简短、可直接粘贴的简报，说明如何将购买 ChatGPT 广告位与追踪 ChatGPT 自然曝光结合起来。该简报绝不会注入工具结果。

开发

Python：

cd services/openai-ads-mcp/python
python -m pytest -q
python -c "import openai_ads_mcp; print('ok')"

Node：

cd services/openai-ads-mcp/typescript
npm install
npm run build
npm test
OPENAI_ADS_MCP_READONLY=1 node dist/index.js

OpenAPI 漂移检查：

cd services/openai-ads-mcp/typescript
npm run check:openapi
npm run check:docs

计划任务工作流每周运行这两项检查。OpenAPI 比较会检测架构漂移。指南检查则覆盖可下载架构之外记录的当前行为，包括带标签的洞察范围、obref、移动应用事件、转化优化、广告主就绪情况、必需的聊天卡片图片，以及有限预览版 Bulk API。

发布状态

0.1.7 是 npm、PyPI、托管端点和在线 MCP Registry 条目的当前公开 Beta 版本。Registry 元数据版本不可更改，因此本仓库中仅针对 Registry 的更正应随下一个软件包发布版本一起发布。发布工作会先同步到专用的公开仓库，然后再发布。请参阅 RELEASING.md。

许可证

MIT，版权归 Trakkr 所有。