Apple Ads

短片展示的是使用示例数据的托管版 getmcpads。其中的 MCP Apps 功能，从创意图库和提醒到 Google Sheets 导出和批量启动，都属于托管产品。本仓库提供独立的原生 API 工具。

9 个只读工具 · 11 个写入工具，默认禁用。

使用你自己的平台凭据，以及支持 stdio MCP 的客户端（例如 Claude Desktop、Claude Code 或 Cursor）在本地运行。你的请求会直接发送到平台。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管版。

更新内容

v1.0.0：首个独立版本 · 2026 年 10 月 23 日

• 为 Apple Ads Platform API v1 创建首个独立服务，并与 getmcpads 网关修订版 3e1c2c8 同步。
• 提供 9 个只读工具、11 个选择启用的写入工具和 2 个资源，并保留网关工具名称及 apple_ads_ 前缀。
• 添加 apple_ads_list_ad_accounts，用于替代托管版的账户选择功能，且只返回已配置的账户。
• 使用从环境变量读取的 EC P-256 密钥在本地签署 OAuth 2 客户端凭据。访问令牌仅保存在内存中。
• 要求提供广告账户允许列表，默认设为只读，预览每次写入操作，将更新绑定到快照，并以暂停状态创建实体。
• 使用固定的 Apple 主机，拒绝重定向，限制响应大小，设置请求超时，并且绝不重试结果不确定的写入操作。
• 要求使用 Node.js 22.23.4、24.22.1、26.12.1 或更新版本；若在较旧的运行时启动，则会向 stderr 输出警告。
• 不包含托管版提醒、创意 UI 或 MCP Apps 集成。

完整变更日志 · 所有版本

源码同步信息：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1 或 26.12.1，或这些版本线的更新版本；这些版本包含 2026 年 10 月的安全修复。在较旧的运行时启动时，服务会向 stderr 输出警告。CI 覆盖 Node 22、24 和 26。写入操作仍为可选，并且需要明确确认。托管版提醒、创意集成和 MCP Apps UI 不在此版本范围内。

安装此版本

这是 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本。npm 包发布后，npx -y @getmcpads/apple-ads-mcp-server 将运行当前在 npm 上提供的版本。

git clone --branch v1.0.0 --depth 1 https://github.com/get-mcp-ads/apple-ads-mcp-server.git
cd apple-ads-mcp-server
npm ci
npm run build

配置 MCP 客户端，使其运行 node，并将 dist/cli.js 的绝对路径及下文所述的平台凭据传入。Claude Desktop 的配置如下：

{
  "mcpServers": {
    "apple-ads": {
      "command": "node",
      "args": ["/absolute/path/to/apple-ads-mcp-server/dist/cli.js"],
      "env": {
        "APPLE_ADS_CLIENT_ID": "SEARCHADS.your-client-id",
        "APPLE_ADS_TEAM_ID": "SEARCHADS.your-team-id",
        "APPLE_ADS_KEY_ID": "your-key-id",
        "APPLE_ADS_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem",
        "APPLE_ADS_AD_ACCOUNT_IDS": "123456789"
      }
    }
  }
}

npm run doctor 会检查配置和 Node.js 版本，不会联系 Apple。

更喜欢托管连接？通过托管服务 getmcpads 使用 Apple Ads。连接你的账户，选择助手可以访问的数据，并使用托管 MCP 连接。请查看网站了解当前功能和套餐。

配置

Apple Ads Platform API 使用 OAuth 2 客户端凭据。客户端密钥是一个短时效 JWT，由此服务使用你的私钥签名，然后交换为有效期一小时的访问令牌。请遵循 Apple 的 OAuth 指南：

1. 生成 EC P-256 密钥对，并妥善保管私钥：

   openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
   openssl ec -in private-key.pem -pubout -out public-key.pem
   

2. 使用 API 用户身份登录 Apple Ads，打开 账户设置 > API，粘贴公钥并保存。
3. 复制公钥字段上方显示的 clientId、teamId 和 keyId。

通过客户端的机密配置提供以下环境变量：

变量	用途
APPLE_ADS_CLIENT_ID	“账户设置 > API”中的 clientId。
APPLE_ADS_TEAM_ID	“账户设置 > API”中的 teamId。
APPLE_ADS_KEY_ID	“账户设置 > API”中的 keyId。
APPLE_ADS_PRIVATE_KEY_PATH	未加密 PEM 私钥的绝对路径。设置此项或 APPLE_ADS_PRIVATE_KEY。
APPLE_ADS_PRIVATE_KEY	PEM 文本本身，可替代路径。支持使用转义的 \n 表示换行。
APPLE_ADS_AD_ACCOUNT_IDS	必填，逗号分隔的广告账户 ID，数量为 1 至 200。每个请求都仅限于这些账户。
APPLE_ADS_ENABLE_WRITES	默认为 false。只有值恰好为 true 时才会开放写入操作。

密钥会在启动时读取一次并保存在内存中。支持 PKCS #8 和 SEC1 PEM 格式。此包不会运行 OAuth 浏览器流程，也不会向磁盘写入任何内容。账户范围的请求会携带请求头 X-AP-Context: adAccountId=<id>，这是 Platform API 的要求。请先调用 apple_ads_list_ad_accounts：它会确认 API 用户可以访问哪些已配置账户，以及在这些账户中拥有哪些角色。

安全性与覆盖范围

默认情况下，写入操作会先预览。再次调用并设置 confirm: true 前，请检查确切的账户、目标和参数。 更新预览会返回资源及其变更的 expectedSnapshot。确认调用必须将其传回，以免覆盖期间发生变化的资源。 广告系列、广告组和关键词创建时均为暂停状态。将状态设为 ENABLED 可能会花费广告预算，预览会通过 activationMaySpend 标记这一点。 如果写入结果不确定，请勿自动重试。先读取实体并核对。唯一的自动重放，是访问令牌续期后再次发送一次读取请求。 账户允许列表会在分发前生效，并筛选账户发现结果。系统会检查父级链，因此会拒绝来自其他广告账户的关键词或广告。未知参数会被拒绝。

请求仅发送至 api.ads.apple.com 和 appleid.apple.com。系统会拒绝重定向、设置请求超时并限制响应大小。错误消息包含 Apple 的状态、固定代码和经过审核的验证路径，不包含服务提供商文本，因为其中可能回显值或凭据。 金额使用 Apple 的原生对象：以主要货币单位表示的十进制金额，以及账户币种，例如 {"amount":"1.50","currency":"EUR"}。原生分页、归因指标、报告总计和总计值均会保留。列表和报告响应会添加 nextOffset，末页时其值为 null。

此服务使用 Apple Ads Platform API v1。Apple 在其变更日志中声明，Platform API 取代 Campaign Management API；后者将于 2027 年 1 月 26 日停止服务。 此服务提供与托管网关同步的已审核子集：App Store 搜索结果广告系列、广告组、关键词、广告重命名、应用和报告。不包含否定关键词、创意素材、产品页面、预算订单、批量操作、洞察、建议和 Apple Maps 广告。 请使用 tools/list 或 server-card.json 查看确切的架构。

托管选项

getmcpads for Apple Ads 管理托管连接和账户选择。 托管版与源代码发布版可能有所不同。联系方式：[email protected]。

开发

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

所有测试均使用合成响应和模拟的 fetch 离线运行。不会读取或更改任何真实账户。

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。

9 个读取工具

工具	用途
apple_ads_list_ad_accounts	列出 API 用户可访问的已配置广告账户，以及所属组织和角色
apple_ads_get_account	读取广告账户信息，包括货币、时区和账单配置
apple_ads_get_campaigns	读取一页广告系列，可按状态筛选
apple_ads_get_campaign	读取单个广告系列，并验证其属于该广告账户
apple_ads_get_adgroups	读取一个广告系列中的一页广告组
apple_ads_get_keywords	读取一个广告组中的一页正向关键词
apple_ads_get_app	读取广告账户可用的 App Store 应用元数据
apple_ads_get_app_eligibility	在创建广告系列前，检查应用是否符合广告投放资格及其店面
apple_ads_get_report	读取广告系列、广告组、广告、关键词或搜索词的效果数据及原生汇总值

11 个写入工具

默认禁用。除非明确确认，否则调用只会预览。使用前请检查配置和确切架构。

工具	用途
apple_ads_create_campaign	为符合条件的应用创建已暂停的 App Store 搜索结果广告系列
apple_ads_create_adgroup	在已验证的广告系列下创建已暂停的手动按点击付费广告组
apple_ads_create_keyword	在已验证的广告组中创建已暂停的正向关键词
apple_ads_create_account	在 API 用户所属的组织中创建广告账户
apple_ads_update_campaign	更改广告系列名称、状态或每日预算，并绑定到预览快照
apple_ads_update_adgroup	更改广告组名称或状态，并绑定到预览快照
apple_ads_update_keyword	更改关键词状态或出价，并绑定到预览快照
apple_ads_rename_campaign	重命名广告系列
apple_ads_rename_adgroup	重命名广告组
apple_ads_rename_ad	重命名广告
apple_ads_rename_ad_account	重命名广告账户，仅发送名称

资源

资源	内容
apple-ads://guide	账户范围、金额单位、报告规则、分页和写入安全
apple-ads://report-catalog	原生报告指标、可加总指标、分组维度及各报告层级的规则

许可证

Apache License 2.0。请参阅 NOTICE。

更多 getmcpads 项目

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。有疑问？请联系：[email protected]。