如果希望 Codex 通过本地 SearchAds Manager App 操作 Apple Search Ads，而非使用自定义 API 脚本，请参阅本页。

1. 设置 macOS App

1. 1 Codex

   向本地 MCP 服务器发送请求。

2. 2 SearchAds Manager

   在你的 Mac 上运行服务器并处理请求。

3. 3 Apple Ads

   返回账户数据或执行已获授权的广告系列操作。

保持 SearchAds Manager 在你的 Mac 上运行。它会使用你在应用中配置的 API 访问权限连接到 Apple Ads。

1. 在 macOS 上启动 SearchAds Manager。
2. 打开 Settings（设置）。
3. 如果尚未设置，请配置常规的 Apple Search Ads 凭据。
4. 打开自动化，然后找到Codex MCP 服务器部分。
5. 启用服务器。
6. 按需检查或更改端口和令牌。
7. 点击 Apply Server Settings（应用服务器设置）。

在 Mac 上打开“设置” → “自动化”，启用本地 MCP 服务器。应用服务器设置，然后从应用中复制 Codex 命令。

如果尚未配置凭据，请按照 Apple 的 OAuth 指南操作：为 Apple Search Ads API 实现 OAuth。

2. 将服务器添加到 Codex

设置卡片会显示应运行的确切命令。命令格式如下：

codex mcp add searchads --url "http://127.0.0.1:7717/mcp?token=YOUR_TOKEN"

添加之后：

1. 保持 macOS App 运行。
2. 在要工作的代码仓库中启动新的 Codex 会话；如果客户端支持，也可重新连接 MCP 服务器。
3. 使用 searchads 服务器执行报表和写入操作，而非手动编写 API 脚本。

3. 推荐的 Codex 工作流程

1. 需要 adam_id 时，先调用 list_apps。
2. 创建广告系列前，如果需要有效的国家代码，请调用 list_supported_countries。
3. 更改前，使用 get_campaign_report、get_adgroup_report 和 get_keyword_report 检查表现。
4. 更改前，使用 list_campaigns、list_adgroups 和 list_keywords 检查当前状态。
5. 创建流程请使用 create_campaigns、add_adgroups 和 add_keywords。
6. 使用 update_campaigns、update_adgroups 和 update_keywords 进行受控编辑。
7. 仅在明确进行破坏性清理时，使用 delete_campaigns、delete_adgroups 和 delete_keywords。
8. 写入操作宜采用小批量、范围明确的方式，以便检查失败原因。

4. 故障排除

1. 如果 Codex 无法连接，请确认 macOS App 已打开，且服务器状态显示为 Running（运行中）。
2. 如果工具调用因配置错误而失败，请重新检查 App 设置中的 Apple Search Ads 凭据。
3. 如果重新生成令牌或更改端口，请使用新 URL 重新运行 codex mcp add ...。

5. 临时冒烟测试提示词

显示可选的冒烟测试提示词

在同一 Codex 会话中运行以下提示词，以便它记住所创建的测试 ID。

使用临时测试命名前缀，例如 mcp-smoke-...，并在结束时删除所有测试内容。新建测试实体在报表中的指标通常为零，但这仍可验证 MCP 报表调用链路。

发现提示词

仅使用 `searchads` MCP 服务器，准备一个 MCP 冒烟测试环境。

1. 找到一个我拥有且可以安全用于临时测试广告系列的应用。优先选择与“Monitor and Manage Search Ads”匹配的应用；如果没有，则列出我拥有的前 5 个应用并选择一个。
2. 调用 `list_supported_countries`，如果支持 `US`，就选择它。否则，选择一个受支持的国家，并告诉我所选的国家代码。
3. 调用 `list_campaigns`，查找名称以 `mcp-smoke-` 开头的广告系列。
4. 告诉我选定的 `adam_id`、国家代码，以及一个格式为 `mcp-smoke-YYYYMMDD-HHMMSS` 的唯一测试前缀。
5. 暂时不要创建任何内容。

创建广告系列提示词

仅使用 `searchads` MCP 服务器，为之前选定的应用和国家创建一个名为 `<PREFIX>-campaign`、处于暂停状态的临时测试广告系列。

使用：
- 选定的 `adam_id`
- 一个国家代码
- `daily_budget_amount` 设为 5
- `currency` 设为 `USD`

创建后，使用测试前缀调用 `list_campaigns`，并返回新的 `campaign_id`。

广告系列报表与更新提示词

仅使用 `searchads` MCP 服务器：

1. 针对 `<CAMPAIGN_ID>` 调用 `get_campaign_report`，并指定 `days: 0`。
2. 使用 `update_campaigns` 更新该广告系列，将每日预算改为 6 USD，状态改为 `ENABLED`。
3. 再次使用测试前缀调用 `list_campaigns`。
4. 总结广告系列更新前后的状态。

添加广告组提示词

仅使用 `searchads` MCP 服务器，向 `<CAMPAIGN_ID>` 添加两个处于暂停状态的广告组：

1. `<PREFIX>-ag-1`
2. `<PREFIX>-ag-2`

使用：
- `default_bid_amount` 设为 1
- `currency` 设为 `USD`
- `automated_keywords_opt_in` 设为 false

创建后，针对该广告系列调用 `list_adgroups`，并返回两个 `ad_group_id` 值。

广告组报表与更新提示词

仅使用 `searchads` MCP 服务器：

1. 针对 `<CAMPAIGN_ID>` 调用 `get_adgroup_report`，并指定 `days: 0`。
2. 使用 `update_adgroups` 更新 `<PREFIX>-ag-1`，将状态改为 `ENABLED`，`default_bid_amount` 改为 1.2 USD，`cpa_goal_amount` 改为 4 USD。
3. 再次针对 `<CAMPAIGN_ID>` 调用 `list_adgroups`。
4. 总结更新后的广告组，并返回其 `ad_group_id`。

添加关键词提示词

仅使用 `searchads` MCP 服务器，通过一个 `keyword_set`，向 `<CAMPAIGN_ID>` 中的 `<AD_GROUP_ID>` 添加关键词。

使用：
- `default_bid_amount` 设为 0.8
- `default_currency` 设为 `USD`

添加以下关键词：
1. `<PREFIX> exact`，`match_type` 为 `EXACT`，`status` 为 `ACTIVE`
2. `<PREFIX> broad`，`match_type` 为 `BROAD`，`status` 为 `ACTIVE`

创建后，针对 `<CAMPAIGN_ID>` 和 `<AD_GROUP_ID>` 调用 `list_keywords`，并返回已创建的 `keyword_id` 值。

关键词报表与更新提示词

仅使用 `searchads` MCP 服务器：

1. 针对 `<CAMPAIGN_ID>` 和 `ad_group_ids: [<AD_GROUP_ID>]` 调用 `get_keyword_report`，并指定 `days: 0`。
2. 使用 `update_keywords` 更新 EXACT 关键词，将出价改为 0.9 USD，状态改为 `PAUSED`。
3. 再次针对 `<CAMPAIGN_ID>` 和 `<AD_GROUP_ID>` 调用 `list_keywords`。
4. 总结更新后的关键词，并返回这两个关键词当前的行数据。

清理提示词

仅使用 `searchads` MCP 服务器，清理 MCP 冒烟测试数据。

1. 使用 `delete_keywords` 删除 `<AD_GROUP_ID>` 中的所有测试关键词。
2. 针对 `<CAMPAIGN_ID>` 和 `<AD_GROUP_ID>` 调用 `list_keywords`，确认关键词已删除。
3. 使用 `delete_adgroups` 删除两个测试广告组。
4. 针对 `<CAMPAIGN_ID>` 调用 `list_adgroups`，确认广告组已删除。
5. 使用 `delete_campaigns` 删除测试广告系列。
6. 使用测试前缀调用 `list_campaigns`，确认广告系列已删除。
7. 总结清理结果。