五分钟内在 Claude 或 ChatGPT 中连接 Apple Search Ads

Hermoso 的 Apple Search Ads 连接器把你的 Apple Ads 账户连接到 Claude、ChatGPT、Cursor、CLI 或普通 HTTP，让智能体替你运行 App Store 搜索广告。它会搭建广告系列、广告组、定向关键词和否定关键词，回读 Apple 实际保存的内容，并一直报告到用户安装前输入的搜索词。它创建的所有内容都是暂停状态，开启投放是一个单独的、需要明确确认的步骤。报告可以写入 Google 表格、Looker Studio 仪表板或 JSON 文件，Apple Ads MCP 页面列出了该连接器能做的全部事情。

连接大约需要五分钟。你不需要运行 openssl，也不会把任何 Apple 密码交给 Hermoso。

将 Apple Search Ads 连接到 Claude

要把 Apple Search Ads 连接到 Claude，先把 Hermoso 作为连接器添加到 Claude，然后在 Hermoso 内连接一次你的 Apple Ads 账户。在 Claude 中打开 Customize › Connectors › Add custom connector，名称填 Hermoso，粘贴 https://app.hermoso.ai/mcp，然后用你的 Hermoso 账户批准。Claude 中不需要粘贴任何密钥。接着在 Hermoso 的 设置 › 连接器 中连接 Apple Ads，步骤见本页下方。之后 Claude 就能调用 Hermoso 提供的每个 Apple Ads 工具：用普通语言要求生成报告、修改关键词或新建广告系列即可。在 Claude Code 中则只需两条命令：/plugin marketplace add hermoso-ai/hermoso，然后 /plugin install hermoso@hermoso。Claude 中的 Hermoso 有完整步骤。

将 Apple Search Ads 连接到 ChatGPT

ChatGPT 的方式相同。在 ChatGPT 中打开 Plugins，然后点击 Add › Create MCP App，名称填 Hermoso，把 https://app.hermoso.ai/mcp 粘贴为 Server URL，保持 Authentication 为 OAuth，并用你的 Hermoso 账户批准。如果没有看到 Create MCP App，请先在 设置 › Plugins › Developer mode 中开启一次开发者模式。在 Hermoso 中连接 Apple Ads 之后，ChatGPT 就能拉取你的关键词报告、写入 Google 表格，或起草一个广告系列供你检查。ChatGPT 中的 Hermoso 有详细说明。

Cursor、Codex 及其他 MCP 客户端

任何支持 Model Context Protocol 的客户端都能在同一地址访问相同的工具。Cursor 读取 https://app.hermoso.ai/mcp，地址来自其 mcp.json；Codex 通过 codex plugin marketplace add hermoso-ai/hermoso 安装 Hermoso 插件，从终端驱动同样的工具。无论你使用哪个客户端，你的 Apple 凭据都不会经过聊天。智能体调用的是 Hermoso 的工具，而 Hermoso 使用它持有的密钥对每个发往 Apple 的请求签名。Apple Ads MCP 页面列出了每个工具。

连接后可以问什么

• “拉取上周的 Apple Search Ads 表现，按关键词列出，并给我看单次获取成本最高的十个。”
• “把最近 30 天按广告系列统计的花费、安装量和 CPA 放进一张名为 Apple Ads 的新 Google 表格。”（请先连接 Google Drive。）
• “本月我的美国广告系列中，哪些搜索词带来了安装，而我还没有以精确匹配关键词的方式出价？”
• “在 Brand 广告组中添加 ‘budget planner’ 和 ‘expense tracker’ 作为精确匹配关键词，并把 ‘jobs’ 设为否定词。”
• “Apple 为我的应用推荐哪些关键词？我已经出价的那些关键词，我拿到了多大比例的展示份额？”
• “为我的应用在英国建一个暂停状态的广告系列，每日预算 50 美元，然后给我看 Apple 实际保存的内容。”

读取报告绝不会动用预算。智能体搭建的任何内容都是暂停状态，开启投放的开关需要你明确确认。

先看这一点，它会难倒大多数人

Apple 自己的说明写道：“在 Ads UI 中选择 Account Settings › API，把密钥粘贴到 Public Key 字段。”

对 Account Admin 来说，这个字段并不存在。以管理员身份登录你自己的账户，打开 Account Settings › API，页面上出现的是一张标题为 Manage API Access 的表格（列出第三方服务提供商，只有一个 Remove Access 操作），页面任何地方都没有密钥字段。它看起来就像功能缺失，这正是人们停在这里、断定自己用不了 API 的原因。

其实是可以用的。Public Key 字段属于持有 API 角色的用户，而账户管理员并不是这个角色。Apple 的邀请对话框提供六种角色，其中只有两种是 API 角色：

• API Account Manager：“read and write access to all campaign groups for API management”。如果你想让 Hermoso 搭建广告系列，而不只是报告，就选这一个。
• API Account Read Only：“read only access to all campaign groups for API management”。只够做报告，别无其他。

其余四种角色（Account Admin、Account Finance、Account Read Only 和 Limited Access）根本无法创建 API 凭据。所以解决办法是给你自己发一封邀请：

1. 打开 Account Settings › User Management，选择 Invite Users。
2. 邀请一个你能控制的邮箱（你自己的，或像 ads-api@yourcompany.com 这样的共享邮箱，这样凭据不会随某一个人离开而失效），角色选 API Account Manager。
3. 从该邮箱接受邀请，然后以该用户身份登录 Apple Ads。

现在 Account Settings › API 上就有 Public Key 字段了。

连接步骤详解

1. 在 Hermoso 中开始。设置 › 连接器 › Apple Ads › Connect。Hermoso 会生成一把 EC P-256 签名密钥（即 prime256v1 密钥，与 Apple 两条 openssl 命令所生成的相同），并且只向你显示公钥部分。复制它。
2. 把公钥交给 Apple。以拥有 API 角色的用户身份，打开 Account Settings › API，把它粘贴到 Public Key，然后保存。
3. 把三个 ID 复制回来。Apple 现在会在该字段上方显示 clientId、teamId 和 keyId。三个都要复制。
4. 在 Hermoso 中完成。粘贴这三个 ID 并保存。Hermoso 会与 Apple 交换令牌，并在保存任何内容之前读取你的组织列表，所以 ID 输错会立刻失败，而你仍然能看到自己粘贴的内容，不必等到一小时后第一次取报告时才发现。
5. 选择组织（如果你的凭据覆盖了多个组织）。该连接会固定在你选择的那一个组织上。

出了问题怎么办

API 页面上没有 Public Key 字段

你是以 Account Admin 身份登录的，或者是以四种非 API 角色之一登录的。请邀请你自己为 API Account Manager，然后以该用户身份登录（见上文）。这是 Apple Ads 连接一直无法完成的最常见原因。

Apple 拒绝了凭据

这三个 ID 必须属于 Apple 持有的那把密钥。请从 Public Key 字段正上方重新复制 clientId、teamId 和 keyId，不要从你已经替换掉的旧密钥上复制。如果仍然失败，请在 Hermoso 中重新开始连接：这会生成一对全新的密钥，然后你把新的公钥粘贴到 Apple。

设置会话已过期

Hermoso 会在你去 Apple 粘贴公钥的这段时间内保存生成的私钥，最长 24 小时。超过这个时间它就被删除了，这是有意为之。请重新开始连接，然后粘贴新的公钥。

我已经用 openssl 生成过密钥

那就直接用它。连接时粘贴你现有的 EC P-256 私钥，而不是使用 Hermoso 生成的密钥，你 Apple 账户里已有的公钥会继续有效。它必须是 EC P-256（prime256v1）密钥，Apple 不接受其他曲线。

我管理多个 Apple Ads 组织

请在各自的 Hermoso 配置文件中分别连接每一个。一个连接固定绑定到单个组织，这样才能避免代理商的广告系列落到错误客户的账户里。

Apple Search Ads 连接器能做什么

搭建：create_apple_ads_campaign、create_apple_ads_ad_group、add_apple_ads_keywords、add_apple_ads_negative_keywords、update_apple_ads_object、set_apple_ads_status、delete_apple_ads_object。

读取：list_apple_ads_campaigns（状态、投放状态、每日和总预算、广告系列投放的国家，以及广告无法投放时 Apple 给出的原因）、list_apple_ads_ad_groups（默认出价，以及 Apple 的 Search Match 是否开启）、list_apple_ads_keywords（定向和否定关键词，含匹配类型和出价）、apple_ads_report（在广告系列、广告组、关键词、搜索词或广告层级的展示、点击、安装、花费、TTR、CPT 和 CPA）以及 list_apple_ads_orgs。

以上全部都可以从 Claude、Claude Code、Codex、Cursor、Cline、OpenClaw、Hermes 或任何其他 MCP 客户端调用，也可以从网页工作室调用。无论哪种方式，都是同一个引擎。参见 MCP 概览或广告工具参考。

更多功能：它可以搭建创意和广告（create_apple_ads_creative、create_apple_ads_ad），一次调用加载多达 1,000 个关键词（bulk_apple_ads_keywords），并读取 Apple 自己的数据：apple_ads_keyword_suggestions、apple_ads_impression_share、apple_ads_search_term_popularity 和 apple_ads_change_history。它们都可以在同一个对话中调用。

从 Apple Search Ads 导出数据

同一个连接也可以生成报告。apple_ads_report 会拉取广告系列、广告组、广告、关键词和搜索词的表现（展示、点击、安装、花费、点击率、单次点击成本和单次获取成本），可以是总计，也可以是按小时、天、周或月的序列，每页最多 5,000 行。读取报告绝不会动用预算。数据最终放在哪里由你决定，下面列出了三种最常见的去处。完整指南见 从 Apple Search Ads 导出数据。

将 Apple Search Ads 连接到 Google 表格

在 Google Drive 旁边连接 Apple Ads（一次 Google 授权即可覆盖 Drive、表格和文档），然后让智能体把报告放进一张表格。它会调用 apple_ads_report，然后用 create_sheet 新建一个电子表格，或用 append_to_sheet 把本周的行添加到已有表格中。Hermoso 使用 Google 的 drive.file 权限范围，因此它只能访问它创建的文件，或你选中的文件。分步说明：将 Apple Search Ads 连接到 Google 表格。

将 Apple Search Ads 导出到 Looker Studio

Hermoso 没有原生的 Looker Studio 连接器。Looker Studio 通过它自己的连接器读取 Google 表格，因此上面的表格就是桥梁：把它一次性添加为 Google 表格数据源，搭建仪表板，之后每次追加的数据都会在下一次刷新时显示。Power BI 和 Tableau 也以同样的方式读取同一张表格。Looker Studio 步骤。

将 Apple Search Ads 导出为 JSON

如需原始数据行，请使用 API 密钥通过 Hermoso REST API 调用该工具：POST https://app.hermoso.ai/v1/tools/apple_ads_report，报告参数作为 JSON 请求体，然后从响应的 data.rows 中读取数据行。在终端中，npx -y hermoso call apple_ads_report --json '{...}' --structured 会以 JSON 形式输出相同的结果。完整请求示例。

常见问题

如何将 Apple Search Ads 连接到 Claude？

把 Hermoso 作为自定义连接器添加到 Claude，URL 填 https://app.hermoso.ai/mcp，并用你的 Hermoso 账户批准，然后在 Hermoso 的 设置 › 连接器 中连接 Apple Ads。之后 Claude 就能通过 Hermoso 的 Apple Ads 工具报告、编辑并搭建你的 Apple Search Ads 广告系列。

ChatGPT 能读取我的 Apple Search Ads 数据吗？

可以。在 ChatGPT 中依次点击 Plugins › Add › Create MCP App，添加 https://app.hermoso.ai/mcp，并在 Hermoso 中连接 Apple Ads。之后 ChatGPT 就能按广告系列、广告组、广告、关键词或搜索词拉取展示、点击、安装、花费、TTR、CPT 和 CPA，并把数据行写入 Google 表格。

有 Apple Search Ads 的 MCP 服务器吗？

有。Hermoso 托管的 MCP 服务器位于 https://app.hermoso.ai/mcp，为 Claude、ChatGPT、Cursor、Codex 或任何 MCP 客户端提供完整的 Apple Ads 工具集：报告、广告系列、广告组、关键词和否定词、创意和广告，以及 Apple 的关键词推荐。它搭建的所有内容都是暂停状态。

为什么 Apple Ads API 页面上没有 Public Key 字段？

因为你是以 Account Admin 身份登录的。Apple 只会为持有 API 角色的用户显示该字段。管理员看到的是一张标题为 “Manage API Access” 的第三方服务提供商表格，页面上任何地方都没有密钥字段。请在 Account Settings › User Management 中把自己邀请为 API Account Manager，然后以该用户身份登录，字段就会出现。

我需要哪个 Apple Ads 角色？

如果你希望 Hermoso 搭建广告系列、广告组和关键词，选 API Account Manager。Apple 对它的描述是 “read and write access to all campaign groups for API management”。如果你只需要报告，API Account Read Only 就够了。Apple 提供的其余四种角色（Account Admin、Account Finance、Account Read Only 和 Limited Access）根本无法创建 API 凭据。

我需要运行 openssl 吗？

不需要。Apple 自己的说明会给你两条 openssl 命令；Hermoso 会为你生成 EC P-256 密钥对，并且只向你显示公钥部分。私钥用于为你的请求签名，你永远看不到它、也不需要粘贴或保存它。如果你已经用其他工具生成过密钥，也可以改用它。

连接 Apple Ads 会产生费用或动用预算吗？

不会。读取操作可以随意调用，Hermoso 创建的每个对象都是暂停状态，且没有覆盖选项。启用对象是唯一会打开真实投放的开关，并且需要明确确认。

clientId、teamId 和 keyId 是什么？

它们是你保存密钥后，Apple 在 Public Key 字段上方打印的三个标识符。它们向 Apple 标识你的 API 用户；私钥则证明你就是本人。把这三个都粘贴回 Hermoso，连接即告完成。

一个连接能覆盖多个 Apple Ads 组织吗？

一个连接在创建时会固定绑定到你选择的那一个组织。Apple 把 orgId 看作类似广告系列组，因此一个登录可能覆盖多个组织。为每个组织都有一个客户的代理商，应在各自的 Hermoso 配置文件中分别连接。

我每 180 天都要轮换一次密钥吗？

不需要。Apple 将客户端密钥的有效期限制为 180 天，这就是为什么 Apple 自己的说明会让你记下轮换的日程。Hermoso 持有私钥，并为每次令牌交换签发一个新的短期密钥，因此不会有任何东西躺在配置文件里等待过期。

我能把 Apple Search Ads 数据导出到 Google 表格或 Looker Studio 吗？

可以。在 Hermoso 中把 Google Drive 连接在 Apple Ads 旁边，你的智能体就会通过 create_sheet 或 append_to_sheet 把报告写入 Google 表格。Hermoso 没有原生的 Looker Studio 连接器；Looker Studio 通过它自己的 Google 表格连接器读取这张表格。

我能以 JSON 形式获取 Apple Search Ads 数据吗？

可以。用 API 密钥调用 Hermoso API 的 POST /v1/tools/apple_ads_report 并读取 data.rows，或者在 CLI 中运行 hermoso call apple_ads_report 并加上 --structured。