Apple Ads MCP

一个本地优先的 Model Context Protocol 服务器，用于 Apple Ads Platform API v1。它为 Codex、Claude 及其他 MCP 客户端提供类型化的工具，用于 App Store 广告研究、报告、审计以及受回执门控的广告系列管理。

Apple Ads MCP 是独立的开源软件。它与 Apple Inc. 无关联，未获其认可，也不受其赞助。Apple Ads 和 App Store 是 Apple Inc. 的商标。

为什么选择 Apple Ads MCP

• 面向智能体的工具： 发现自有 App、研究关键词、检查报告、审计广告系列，并准备范围有限的变更。

• 本地凭据： 私钥保留在您的机器上；OAuth 令牌和操作回执只存在内存中。

• 默认只读： 无需启用写入即可完成研究和报告。

• 显式账户路由： 每个账户级工具都需要一个 profile 和一个 adAccountId。

• 安全的变更： 每次写入操作都需要预览、十分钟有效的单次回执，以及当前状态复核。

• 有界输出： 使用结构化的 MCP 内容、受限数组、分页、速率限制元数据，以及结构化的 Apple 错误。

• 可移植运行时： 一个 Go 二进制即可运行于 macOS、Linux 和 Windows，另附 OCI 镜像。

Related MCP server: OpenAI Ads MCP

发布状态

v0.1.0 是首个公开版本。完整的本地测试套件、竞态检测器、静态分析、漏洞扫描、密钥扫描、分发明验和真实 MCP stdio 测试均获得通过。

在受运营方控制的 Apple Ads 账户上进行的一次性私人实测验收验证了：

• OAuth、账户发现、组织与所属 App 查询；

• 店面可用性、关键词建议、热度洞察和有界报告；

• 预览 → 回执 → 应用 → 直接 API 回读；

• 暂停广告系列、广告组、定向关键词和否定关键词的创建；

• 漂移拒绝、单次回执、只读恢复和零广告花费。

本仓库不存储任何凭据、账户导出、私有广告系列数据或真实回执。

功能

读取工具

回执门控的写入工具

• 创建和更新广告系列、广告组、目标关键词和否定词。

• 使用针对特定流量的预览基础来管理 App Store 素材，但支持程度仍取决于 Apple 的投放位置和产品页组合。

• 让广告系列暂停/恢复、广告组出价和 CPA 上限的预览。

• 通过 operations_apply 仅应用一个预览。

• 通过 operations_inspect 和 operations_verify 检查或验证有歧义的操作。

没有通配的原始请求工具。Apple 过期地图、旧版 Campaign Management API v5、自动增加预算、抢夺、以及应用/忽略建议的操作都被有意排除。

安全模型

仅当满足以下所有条件时，写入操作才可能发生：

1. Apple 用户对特定广告账户具有已承认的 API 写入角色。

2. 服务器使用 --allow-writes 启动。

3. 所选 profile 设置了 allowWrites: true。

4. 专门的 *_preview 工具返回一个回执。

5. operations_apply 收到同一个未过期的回执。

6. 当前 Apple 资源的状态仍与预览期间读取的状态一致。

回执在十分钟后过期且只能使用一次。发生不确定的传输故障后，绝不再重试。服务器返回 committed_unverified，并要求在继续任何后续的写入前先进行直接状态检查。

对于常规的研究和报告，请直接运行服务器且不使用 --allow-writes，并将所有 profile 保持 allowWrites: false。

安装

GitHub Releases

从 GitHub Releases 下载适合您平台的压缩包。每次发布都包含 SHA-256 校验和和 SPDX 软件清单。

Apple silicon 示例：

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Homebrew formula

该发布附带一个校验和固定的公式作为资源：

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp.rb
brew install --formula ./apple-ads-mcp.rb

OCI 镜像

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.1.0

该镜像默认以 serve --stdio 运行。以只读方式挂载 accounts.json 和对应的私钥。如果密钥仅所有者可读，请以匹配的主机 UID/GID 运行容器。

从源码构建

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./bin/apple-ads-mcp ./cmd/apple-ads-mcp

需要 Go 1.26.6 以上版本。

Apple Ads API 设置

Apple Ads API 的访问权限与 App Store Connect 的访问权限不同。Apple Ads 账户管理员必须添加一个具有相应角色的 API 用户；在需要更改广告系列之前，请优先使用 API Account Read Only。

在本地生成 ES256 密钥对：

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

仅将公钥上传至 Apple Ads。将私钥保存在仓库之外，并且绝不要将其粘贴到 Agent 对话、issue 或日志中。

在 Apple 注册公钥插件后，记下 Apple Ads UI 中显示的公开 client ID、team ID 和 key ID。

配置

交互地创建 profile：

apple-ads-mcp config init

默认配置路径为：

~/.config/apple-ads-mcp/accounts.json

等效 JSON：

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false
    }
  ]
}

在 POSIX 系统上，两个文件都必须仅所有者可访问：

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

配置文件仅存储项目元数据和私钥路径，从不会内嵌私钥。

验证认证并发现可访问的账户：

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

配置优先级：

1. --config

2. APPLE_ADS_MCP_CONFIG

3. ~/.config/apple-ads-mcp/accounts.json

4. 单配置文件 APPLE_ADS_* 环境变量

支持的环境变量为：APPLE_ADS_PROFILE、APPLE_ADS_CLIENT_ID、APPLE_ADS_TEAM_ID、APPLE_ADS_KEY_ID、APPLE_ADS_PRIVATE_KEY_PATH、APPLE_ADS_AD_ACCOUNT_ID 和 APPLE_ADS_ALLOW_WRITES。

连接 MCP 客户端

通过 stdio 启动服务器：

apple-ads-mcp serve --stdio

用于 Codex、Claude Desktop 或其他 stdio 场景的通用 MCP 配置：

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Claude Code：

claude mcp add apple-ads -- apple-ads-mcp serve --stdio

发布包还包含 Codex 插件元数据和 apple-ads-operator 技能。该技能引导你完成 Catalyst 框架，而不会在占据引领时放入任何凭据。

为单个会话启用写入

在不干扰持久化配置的情况下，保持 allowWrites: false。对于明确授权的维护会话，可以同时临时打开两个开关：

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

Apple ACL、显式的 profile、显式的 adAccountId、预览、回执绑定、过期和偏移仍然生效。仅开启写入的开关本身不会改任何内容。

已知的平台行为

• Apple Ads 没有公开沙盒；自动化的真实环境 CI 在 CI 中可选启动，并严格只读。

• 可用性、建议、热度值、推荐和报告因账户、App、国家/地区及历史记录而异。

• 冷启动的账户可能不会返回目标 CPA 或预算推荐。

• Apple 可能返回某 API 微信的验证错误或服务器的错误。这时 MCP 会仅保留 4xx 安全信息，并隐去可重试的服务器错误。

• 在实体验收时，Apple 拒绝了 APPSTORE_SEARCH_RESULTS 上单独创建 Ad 对象，而是让搜索广告使用已发布 App 的默认产品页。

• 广告系列名称由 Apple 验证；Web 界面接受的某些标点可能被 API 拒绝。

• 性能报告在获得数据之前一直为空又完整。安装到订阅或试用将属归属的归因逻辑内，而非从本 API 获取。

• 完整的 MCP conformity runner 测试仍未通过，因为该 runner 只支持 URL 而不支持 stdio 进程；本仓库则通过 Go SDK 验证了真实的可 send 命令会话。

开发

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py

实时测试需要显式的本地凭据，并绝不会自动进行变更操作。参见 CONTRIBUTING.md、SECURITY.md、路线图 和机器可读的 操作矩阵。

发布产物

每次上传的 Tag 都会发布：

• AMD64 和 ARM64 的 macOS、Linux、Windows 压缩包 （如平台匹配）

• checksums.txt 包含 SHA-256 摘要额度；

• 由 Syft 生成的 SPDX 软件物料清单；

• 已固定校验和的 Homebrew formula；

• 支持 AMD64 和 ARM64 Linux 的多架构 OCI 镜像；

• MCP Registry 包元数据。

许可证

MIT