aapl-ads-mcp

一个将 Claude（以及任何兼容 MCP 的客户端）连接到 Apple Search Ads API v5 的 MCP 服务器。

这是什么

MCP (Model Context Protocol) 是一种开放标准，允许 AI 助手调用外部工具。此服务器实现了 MCP stdio 传输，并公开了 9 个只读工具，用于查询您的 Apple Search Ads 账户——包括广告系列、广告组、关键词和效果报告。

您只需安装一次，将其指向 Claude Desktop，然后用简单的英语提问即可，例如：“上个月哪些关键词带来的安装量最多？”或“显示本周零展示的广告系列。”

Related MCP server: tiktok-ads-mcp

为什么选择它

官方的 ASA 仪表板适合人类查看，但不适合临时分析或自动化报告。现有的 MCP 替代方案要么是 SaaS（您需要交出密钥），要么无人维护。这是一个您可以自行托管、开源且完全掌控的选项。

功能

• list_orgs — 验证身份验证，列出可访问的组织

• list_campaigns — 枚举广告系列，可选择按状态过滤

• list_ad_groups — 获取指定广告系列的广告组

• list_keywords — 获取包含出价金额和匹配类型的定位关键词

• get_campaign_report — 按广告系列获取展示次数、点击次数、安装次数、支出、CPI 和 TTR

• get_ad_group_report — 按广告组细分的相同指标

• get_keyword_report — 按关键词的效果，支持周/日/月粒度

• get_search_terms_report — 触发您广告的真实搜索查询（对发现新词最有用）

所有工具默认查询过去 30 天的数据。报告支持 HOURLY（小时）、DAILY（天）、WEEKLY（周）和 MONTHLY（月）粒度。

限制

• 设计为只读。 此版本没有写操作（创建、更新、暂停）。

• 需要 Apple Search Ads 广告系列管理 API 访问权限。 您需要在 ASA 账户中创建一个 API 用户并生成 ES256 密钥对。

• 聚合安装指标无需应用端集成。 ASA 报告中的 tapInstalls、viewInstalls 及相关字段由 Apple Search Ads 直接填充，无需在您的应用中集成任何 SDK。仅当您希望在应用内将安装归因于特定广告系列（例如用于个性化引导）时，才需要 AdServices / AdAttributionKit。

• 单个组织。 组织 ID 在配置中固定。未实现多组织切换。

设置

1. 生成 ES256 密钥对

使用现代的 genpkey 命令——它直接生成 PKCS#8 格式，这是此服务器所要求的。旧的 ecparam -genkey 生成的是 SEC1 格式，会导致启动错误。

# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem

# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pem

验证私钥是否以 -----BEGIN PRIVATE KEY----- 开头（而不是 -----BEGIN EC PRIVATE KEY-----）。如果它以 EC 变体开头，请转换它：

openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem

如果可能，请将 private-key.pem 存储在仓库根目录之外（例如 ~/.ssh/asa-private-key.pem）。

2. 在 Apple Search Ads 中创建 API 用户

1. 前往 ASA → 账户设置 → 用户管理

2. 点击 创建用户，选择 API 账户只读 角色（推荐用于此服务器）。API 广告系列管理员 也可以，如果您计划稍后使用写工具扩展服务器，它会增加写权限。

3. 前往 API 选项卡，点击 创建客户端

4. 上传 public-key.pem

5. 从确认屏幕复制 client_id、team_id 和 key_id

6. 在 账户设置 → 概览 中找到您的 org_id

3. 克隆并构建

git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build

4. 配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "aapl-ads": {
      "command": "node",
      "args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",

"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"

} }

} }

注意： ASA_PRIVATE_KEY_PATH 必须是绝对路径。波浪号 (~) 不会被 Node.js 展开——请使用完整路径。

对于无法挂载文件的容器或云部署，请改为设置 ASA_PRIVATE_KEY 为内联 PEM 内容（保留换行符）。如果两者都设置了，ASA_PRIVATE_KEY 优先。

重启 Claude Desktop。询问“run health check”以验证服务器是否已连接。

使用示例

这些是服务器运行后可在 Claude Desktop 中使用的自然语言提示：

List my Apple Ads campaigns

显示过去 30 天的广告系列效果

上周我的品牌广告系列中哪些关键词带来了安装？

过去一个月有哪些搜索词触发了我的广告？重点关注那些有展示但没有安装的词。

比较 2025 年第一季度所有广告系列的每周支出

显示广告系列 1234567890 中的广告组及其出价金额

## Development

```bash
npm run build      # compile TypeScript
npm test           # run test suite (Vitest)
npm run typecheck  # type-check without emitting
npm run lint       # Biome lint
npm run format     # Biome format (write)

MCP Inspector

要在没有 Claude Desktop 的情况下交互式调试工具调用：

npx @modelcontextprotocol/inspector node dist/index.js

在连接前在 Inspector UI 中设置环境变量。

预提交钩子 (Pre-commit hooks)

克隆后在本地安装 lefthook 钩子：

npx lefthook install

这会设置：

• gitleaks protect --staged — 阻止包含密钥的提交

• 对暂存的 .ts 文件进行 Biome lint 检查

• TypeScript 类型检查

贡献

有关技术细节，请参阅 docs/ARCHITECTURE.md：身份验证流程、HTTP 客户端设计、工具模式、报告模式怪癖以及开发过程中学到的 ASA v5 经验。

欢迎提交错误报告和拉取请求。

安全性

• 切勿提交 .env 或 *.pem 文件——两者都在 .gitignore 中

• 将 private-key.pem 保持在仓库根目录之外

• 访问令牌仅保存在内存中，从不写入磁盘

• 如果您怀疑密钥已泄露，请在 ASA → 账户设置 → API 中轮换它

许可证

MIT — 请参阅 LICENSE。