Hypd Ai Openai Ads

openai-ads-mcp

面向 OpenAI Ads（广告主）API 的模型上下文协议（MCP）服务。它让兼容 MCP 的客户端——Claude Desktop、Cursor、VS Code 等——通过自然语言读取你的 OpenAI Ads 广告系列、广告组、广告和效果洞察。

只读。 首个版本只会读取数据——不会创建、编辑或暂停任何内容，也不会花费预算。写入操作已列入路线图。

非官方。 这是一个社区项目，与 OpenAI 无关联，也未获其认可。请参阅免责声明。

---

概览

OpenAI Ads API 提供广告主的账户、广告系列、广告组、广告和报告数据。此服务将该 API 的读取端点封装为 MCP 工具，让 AI 助手能够回答如下问题：

• “我的 OpenAI Ads API 密钥能正常使用吗？它关联的是哪个账户？”
• “列出我的有效广告系列及其预算。”
• “按天显示广告系列 cmp_123 过去 30 天的支出、点击量和 CTR。”
• “广告组 adg_456 中哪些广告仍在等待审核？”

功能

• 11 个只读工具，涵盖账户、广告系列、广告组、广告和各个层级的效果洞察。
• 忠实返回——API 的 JSON 会原样返回，不会丢失任何信息。
• 错误信息清晰——HTTP 状态码和 API 错误正文会呈现给模型，而不会被吞掉。
• 支持微单位——每个工具说明都会解释微单位约定，方便助手展示人类可读的货币金额。
• 透传游标分页（limit、order、after、before）。
• 通过 npx 零安装——运行 npx -y @hypd-ai/openai-ads-mcp，无需克隆或构建。

工具

工具	功能说明
get_ad_account	获取配置密钥对应的广告账户。适合作为连通性检查。
list_campaigns	列出广告系列（目标、预算、国家/地区定位）。
get_campaign	按 ID 获取单个广告系列。
list_ad_groups	列出广告组，可按广告系列筛选。
get_ad_group	按 ID 获取单个广告组（出价配置、上下文提示）。
list_ads	列出广告，可按广告组筛选。
get_ad	按 ID 获取单个广告（创意素材和审核状态）。
get_account_insights	整个账户的效果洞察。
get_campaign_insights	单个广告系列的效果洞察。
get_ad_group_insights	单个广告组的效果洞察。
get_ad_insights	单个广告的效果洞察。

洞察工具接受 since/until（YYYY-MM-DD）来指定报告时间范围，还接受 time_granularity（daily/none）、aggregation_level、fields、sort、filters、limit（1–10000）以及 after/before 游标。

前置条件

• Node.js 20 或更高版本。
• OpenAI Ads API 密钥。 在 ads.openai.com 创建 Ads 账户（目前仅限 美国），然后从 Settings → ads.openai.com/settings 生成密钥。请参阅快速入门和身份验证文档。每个密钥都仅适用于一个广告账户。

安装与配置

MCP 客户端会将服务作为子进程启动，并通过环境变量传入你的 API 密钥。

已在 npm 上发布为 @hypd-ai/openai-ads-mcp——npx 会为你获取它，因此无需克隆或构建。若要运行最新的未发布 main，请将 @hypd-ai/openai-ads-mcp 替换为 github:HYPD-AI/openai-ads-mcp（首次启动时会从源代码构建——请参阅从源代码运行）。

在下方添加适用于你的客户端的代码片段。

Claude Desktop

编辑你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

重启 Claude Desktop，然后询问：“使用 openai-ads 工具查找我的广告账户。”

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）：

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json。VS Code 可以提示你输入密钥，并通过 inputs 将其作为机密保存：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "openai_ads_api_key",
      "description": "OpenAI Ads API key",
      "password": true
    }
  ],
  "servers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "${input:openai_ads_api_key}"
      }
    }
  }
}

其他 MCP 客户端

任何通过 stdio 使用 MCP 的客户端都可以使用。设置环境变量中的 OPENAI_ADS_API_KEY，然后运行 npx -y @hypd-ai/openai-ads-mcp（或 node /path/to/dist/index.js）。

配置

变量	必需	默认值	说明
OPENAI_ADS_API_KEY	是	—	你的 OpenAI Ads API 密钥，以 Bearer 令牌形式发送。
OPENAI_ADS_BASE_URL	否	https://api.ads.openai.com/v1	覆盖 API 基础 URL（适用于测试或代理）。

请参阅 .env.example。

关于“micros”的说明

名称以 _micros 结尾的字段——例如广告系列的 lifetime_spend_limit_micros 或广告组的 max_bid_micros——以 micros 为单位：

1,000,000 micros = 1 unit of the account's currency   (e.g. $1.00 = 1,000,000 micros)

因此，lifetime_spend_limit_micros 为 25000000 时，表示 $25.00。将 _micros 值除以 1,000,000，即可换算为便于理解的金额；反向换算则乘以 1,000,000。

洞察指标不是 micros。 spend、cpc 和 cpm 等报告值已经是账户货币的十进制金额（例如，spend: 42.75 表示 $42.75）。

按设计只读

此版本仅注册读取（GET）工具——每个工具都标注了 MCP readOnlyHint，以便行为规范的客户端知道它们无法更改状态。这里没有任何可创建、编辑、暂停或删除内容的工具，也没有任何可花费预算的工具。写入操作将在经过审慎评估的独立步骤中推出（请参阅路线图）。

从源代码运行

git clone https://github.com/hypd-ai/openai-ads-mcp.git
cd openai-ads-mcp
npm install
npm run build

然后将 MCP 客户端指向构建后的入口文件：

{
  "mcpServers": {
    "openai-ads": {
      "command": "node",
      "args": ["/absolute/path/to/openai-ads-mcp/dist/index.js"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

使用 MCP Inspector 试用

OPENAI_ADS_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

开发

npm install          # install dependencies
npm run dev          # rebuild on change (tsup --watch)
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest
npm run build        # bundle to dist/

项目结构：

src/
  index.ts        # bin entry: load config, build server, connect stdio
  server.ts       # buildServer(): McpServer + register all tools
  client.ts       # OpenAIAdsClient: auth, URL building, errors
  config.ts       # environment parsing & validation
  schemas.ts      # shared zod shapes (pagination, insights) + micros note
  tools/          # one file per resource (account, campaigns, ad-groups, ads, insights)
test/             # vitest specs (config, client, in-memory server)

工具与 API 的映射关系

所有端点都位于基础 URL 下（默认值为 https://api.ads.openai.com/v1）。

工具	方法	端点
get_ad_account	GET	/ad_account
list_campaigns	GET	/campaigns
get_campaign	GET	/campaigns/{campaign_id}
list_ad_groups	GET	/ad_groups
get_ad_group	GET	/ad_groups/{ad_group_id}
list_ads	GET	/ads
get_ad	GET	/ads/{ad_id}
get_account_insights	GET	/ad_account/insights
get_campaign_insights	GET	/campaigns/{campaign_id}/insights
get_ad_group_insights	GET	/ad_groups/{ad_group_id}/insights
get_ad_insights	GET	/ads/{ad_id}/insights

路线图

• ✍️ 写入操作 — 创建和更新（通过 POST）广告系列、广告组和广告，以及专用的状态转换（POST .../activate、.../pause、.../archive）。HTTP 客户端已支持 POST；由于这些操作会影响投放和支出，因此需要显式启用后才能使用。
• 🖼️ 创意素材上传 — 使用 POST /upload（JSON image_url 或 multipart/form-data）为广告创意添加图片。
• 🌍 广告系列定向 — 包含或排除国家/地区（targeting.locations.countries）。
• 📈 支持 Conversions API。
• 🌐 为托管部署提供 远程/HTTP 传输。
• 📦 发布 npm 版本，让 npx -y openai-ads-mcp 开箱即用。

参与贡献

欢迎贡献！请阅读 CONTRIBUTING.md。简而言之：对于重大更改，请先提交 issue 进行讨论；确保 npm run lint && npm run typecheck && npm test 全部通过；并为新行为添加测试。

免责声明

这是一个非官方的社区项目，与 OpenAI 没有关联，也未获其认可或赞助。“OpenAI”及相关名称和徽标均为 OpenAI 的商标。通过此工具使用 OpenAI Ads API 须遵守 OpenAI 的条款和政策。本工具按“原样”提供，不附带任何形式的保证 — 请参阅许可证。

许可证

MIT © HYPD AI