内容
ai-ads-mcprakkr 跟踪整个 AI 可见性漏斗，包括和付费流量。这是开源的付费端配套工具。
`openai-ads-mcp` 是一个为 OpenAI 广告、ChatGPT 广告和 OpenAI 广告商 API 提供的类型化的模型上下文协议（MCP）服务器。它允许 Claude、Cursor、Codex、VS Code 等 MCP 客户端检查广告账户、读取性能洞察、创建暂停的广告活动、上传创意、管理受众并发送转化事件。
它有两个运行时环境，具有相同的工具名称、参数、默认值、安全模型和已验证的 OpenAPI 参考：
| 运行时环境 | 最佳安装方式 | 包路径 --- | --- | --- |
| Python | `uvx openai-ads-mcp` | `python/` |
| Node | `npx -y openai-ads-mcp` | `typescript/` |
目标很简单：通过 AI 助手使 OpenAI 广告可操作，而不会使意外触发消费变得容易。
## 安装
使用 `uvx` 安装 Python 版本：
```bash
uvx openai-ads-mcp
```
使用 pip 安装 Python 版本：
```bash
python -m pip install openai-ads-mcp
openai-ads-mcp
```
使用 `npx` 安装 Node 版本：
```bash
npx -y openai-ads-mcp
```
使用 npm 安装 Node 版本：
```bash
npmg openai-ads
openai-ads-mcp
```
从本 mon 进行本地开发：
```bash
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 广告管理器中创建广告 API 密钥，然后将其作为环境变量传递。
```bash
export OPENAI_ADS_API_KEY="..."
```
推荐的首次连接：
```bash OPENAI_ADS_MONLY=1
uvai-ads-mcp或使用 Node：
```bash
export OPENAI_ADCP_READONLY=1px -y openai-mcp
```
只会隐藏所有写入工具。它们在 `tools/list` 中不可用，也无法被调用确认了账户并数据，请取消设置 `OPENAI_ADS_MCP` 以启用写入。
变量：
| 用途 |
| --- | --- |
| `OPENAI_ADS_API_KEY` | `api.ads.openai.com` 所需的 bearer。 |
| `OPENAI_ADS_API_BASE_URL` | 用于测试或代理的可 重定向。 |
|AI_ADS_MCP_READONLY` | 设置为 `1` 或 `true` 以仅注册读取工具。 |
| `OPENAI_ADS_BUDGET_CEILING_USD` | 可选预算上限。默认 `100`。 |
## 发现元数据
本仓库包含 `server.json`，用于官方 MCP 注册表和下游 MCP 目录。规范的注册表名称是：
```text
iorakkr-aisearch/openai-ads-mcp
```
Node 包中包含匹配mcpName`，Python 包 README 中包含用于 Py权验证的匹配 `-name` 标记。
注册表元数据还提供了只读 Streamable HTTP：
```text
openai-ads-mcp.trakkr.ai/m```
该托管端点用于发现和只读使用。它不存储或使用 Trakkr 拥有的 OpenAI 广告 API 密钥。
## MCP示例
### Claude Code，Python 运行时环境
```claude mcp add openai-ads \
-e OPENAI_ADS_APIyour_ads_key_here -e OPENAI_ADS_MCP_READONLY= -- uvx openai-ads-mcp
```
### Claude Code，Node 运行时bash
claude mcp add openai-ads \
-e OPENAI_AD_KEY=your_ads_key_here \
-AI_ADS_MCP1 \
-- npx -y openai-ads-mcp
```
### Cursor 或 Claude 桌面版
```json
{
"mcpServers": {
"openai-ads": {
"command": "uvx",
"args": ["openai-ads-mcp"],
"env": "OPENAI_ADS_API_KEY": "_here",
"OPENAI_ADS_MONLY": "1"
}
}
使用 `"command": "npx"` 和 `"args":y", "openai-mcp"]` Node 运行时环境。
### Codex CLI
```
[mcp_servers.openai_ads]
command = "uvargs = ["openai-ads-mcp"]
env = { OPENAI_ADS_API_KEY = "your_ads_key_here", OPENAI_ADS_MCP_READONLY = "1" }
```
### Docker
仓库中包含用于托管 Streamable HTTP 部署的生产 Dockerfile：
```bash
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 部署脚本使用。对于本地标准输入/输出使用，优先使用 `uvx openai-ads-mcp` 或 `npx -y openai-ads-mcp`。
## Streamable HTTP
Node 运行时环境还可以为托管或团队部署提供 Streamable HTTP 服务：
```bash
export OPENAI_ADS_MCP_HTTP_TOKEN="choose_a_long_random_token"
npx -y openai-ads-mcp --http
```
默认值：
- URL：本地环境下为 `http://127.0.0.1:8080/mcp`，或在代理后为 `https://your-host/mcp`。
- 健康检查：`GET /healthz`。
- 远程模式强制 `OPENS_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 路径。默认 `/m |
| `OPENAI_ADS_MCP_HEALTH_PATH` | 健康检查路径。默认 `/healthz`。 |
| `OPENAI_ADS_MCP_HTTP_TOKEN` | 托管客户端所需的选项 bearer 令牌。 |
| `OPENAI_ADS_MCP_HTTP_ALLOW_WRITES` | 设置为 `1` 时，仅允许写入工具通过 HTTP 暴露。 |
| `OPENAI_ADS_MCP_HTTP_CORS_ORIGIN` | 可选的 CORS 源。默认 `*`。 |
对于公共托管端点，默认情况下请禁用写入，并通过您自己的 OAuth 或凭证保险库将广告 API 密钥注入服务器端。不要在浏览器可见的配置中放置共享的广告 API 密钥。
### 公共对于公共发现端点，请使用：
```bash
export OPENAI_ADS_MCP_HOSTED_PUBLIC
export OPENAI_ADCP_TELEMETRY_SALT="long_random_value"
npx -y openai-ads-mcp --```
托管公共模式：
- 强制只读模式
- 如果 `OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1`，则拒绝启动
- 如果存在 `OPENAI_ADS_API_KEY`，则拒绝启动
- 拒绝 `X-OpenAI-Ads-API-Base-Url`
- 初始化和 `tools/list`
- 需要 `X-OpenAds-API-Key` 进行广告 API 工具调用
- 限制发现和工具调用
- 仅记录编辑后的摘要、哈希、状态、延迟和客户端元数据
生产运行手册位于 `HOSTED_DEPLOY 中。
## 工具表面
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` 和 ``。 |
|_campaign` | 在受控工作流中创建暂停、暂停广告组和暂停广告。 |
|_context_hints`随机生成 API 形状context_hints`隐藏的 LLM 调用。 |
| `send_conversions` | 在本地验证后，将转化事件发送到 `https://bzr.openai.com/v1/events?pid=...`。 |
## 安全模型
该服务器可以影响实际的广告支出，因此默认设置非常谨慎。
1. 默认情况下，创建工具处于暂停状态。`build_campaign` 创建的所有对象都处于暂停状态。
2. 激活是单独的工具：`set_campaign_state`、`set_ad_group_state` 和 `set_ad_state`。
3. 设置预算的路径强制执行 `OPENAI_ADS_BUDGET_CEILING_USD`，默认值为 `。
4. 要超过上限，请传递 `confirm_budget=True`。
5. `OPENAI_ADS_MONLY=1` 所有写入工具。
转化摄入验证最多 1000 个事件/调用，时间戳不超过 7 天，时间未来 10 分7. 服务器从不 密钥或转化用户数据。
每个工具都设置了 MCP 注释。使用 `readOnlyHint`。写入工具使用OnlyHint=false`和更改预算的标记为破坏性和开放主机在运行前提示。
## 工作示例
首先，安全连接：
export OPENAI_ADS_API_KEY="..."
AI_ADS_MONLY=1
uvx openai-ads-mcp
```
询问您的
```text
_account 和 list_campaigns。确认广告密钥有效已存在的内容。
```
然后在不使用只读模式的情况下重启并创建一个暂停的广告活动：
```text
使用 draft_context_hints 为“AI 可见软件”生成，针对具有比较意图的增长团队。
然后使用以下参数调用 build_campaign：
- 名称：“AI 可见性类别测试”
- 预算_usd：50
- 广告组：名称“增长团队”，计费事件“点击”，最大出价_usd 1.25，context_hints 来自草稿
- 广告：两个 chat_card 变我上传_id
任何内容。
```
审查返回活动、、广告、预算、定位和状态。当好上线时，显每个层：text
调用 set_campaign_state，状态为“activate”。
调用 set_ad_group_state，状态为“activate”。
对已批准的广告调用 set_ad_state，状态为“activate”。
```
## 有机部分
付费广告的答案：您在哪里购买了注意力？
Trakkr 回答：在 ChatGPT、Perplexity、Gemini、Claude、Google AI 概览、Reddit、引用、排名、竞争对手、情绪、提示、报告和操作等处，您的品牌会如何有机地显示出来？
在 [trakkr.ai](https://trakkr.ai) 跟踪有机侧。在 [trakkr.ai/create](trak/create) 使用 T 生成器将 AI差距转化为内容简该 MCP 还公开了一个可选资源：
```text
openai-ads://trakkr-visibility
```
它返回一个短的、可以直接粘贴的简介，将购买 ChatGPT 广告位与跟踪有机 ChatGPT 可见性联系起来。它从未被注入工具结果中。
## 开发
Python：
```bash
cd services/openai-ads-mcp/python
python -m pytest -q
python -c "import openai_ads_mcp; print('ok')"
```
Node：
```bash
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
```
## 发布状态
该软件包处于测试阶段。在发布第一个公共版本之前，请确认 PyPI 和 npm 包名称 `openai-ads-mcp` 可用。参见 `RELEASING.md`。
## 许可证
MIT，版权归 Trakkr 所有。
