使用说明

Apple Ads MCP

MCP server for the Apple Search Ads API v5.
Connect it to any MCP-compatible AI client and manage your campaigns, keywords, budgets, and reporting through natural language.

Quick Start • Tools • Resources • Prompts • Clients

问你的AI一些事情，比如：

“我的竞选活动上周表现如何？” “暂停品牌活动，将发现预算增加到500美元。” “哪些搜索词触发了我的广告？将最佳搜索词添加为完全匹配的关键字。”

支持54个工具、3个资源和6个提示——活动、广告组、关键字、创意、预算、搜索词、地理定位、印象分享和绩效报告。

一览功能

特性	描述
活动管理	创建、更新、暂停和删除活动和广告组
关键字优化	添加/删除目标和负面关键字，更新出价
执行报告	带有日期预设的活动、广告组、关键字、广告和地理报告
搜索词分析	查看触发广告的实际搜索查询
创意管理	管理广告、创意和产品页面
预算控制	创建和管理预算订单，分析利用率
印象分享	生成和检索印象分享报告
多组织支持	运行时在组织之间切换

快速开始

获取您的Apple凭据（约10分钟，一次性）
生成密钥对（2个命令）
添加到您的MCP客户端
开始聊天

设置

步骤1-邀请API用户

由 账户管理员 在 searchads.apple.com.

首选设置 → 用户管理 → 邀请用户
输入将使用API的人员的电子邮件
设置角色：
- API客户经理 --完全读/写访问
- API帐户只读 --仅查看访问
发送邀请

API用户必须是 不同的Apple ID 来自管理员。如果您是管理员，请使用第二个Apple ID。

步骤2--接受并复制您的凭据

由 受邀用户.

接受电子邮件邀请并登录 searchads.apple.com
首选设置 → API 标签
复制并保存这三个值：
- 可点击 --开始于 SEARCHADS.
- teamId --开始于 SEARCHADS.
- keyId --UUID

步骤3——生成密钥对

打开终端并运行：

openssl ecparam -genkey -name prime256v1 -noout -out ~/apple-ads-key.pem && \
openssl pkcs8 -topk8 -nocrypt -in ~/apple-ads-key.pem -out ~/apple-ads-key-pkcs8.pem

然后生成公钥：

openssl ec -in ~/apple-ads-key-pkcs8.pem -pubout -out ~/apple-ads-key-public.pem

这将创建：

~/apple-ads-key-pkcs8.pem --私钥（请确保其安全，在您的配置中使用）
~/apple-ads-key-public.pem --公钥（接下来上传到苹果）

步骤4--将公钥上传到Apple

打印您的公钥：

cat ~/apple-ads-key-public.pem

复制整个输出（包括 BEGIN / END 行），然后：

首选设置 → API 轻敲 searchads.apple.com
粘贴到公钥领域
保存

步骤5--添加到MCP客户端

在下面选择您的客户并填写您的 可点击, teamId，以及 keyId 从步骤2开始 完整路径 从步骤3开始，将您的私钥。

多个组织？ 省略 ASA_ORG_ID 和使用 list_organizations / switch_organization 在运行时。或者设置它 env 选择默认值。

客户

Claude Desktop

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

{
  "mcpServers": {
    "apple-ads": {
      "command": "npx",
      "args": ["-y", "apple-ads-mcp"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"
      }
    }
  }
}

保存后重新启动Claude Desktop。

Claude Code

claude mcp add apple-ads \
  -e ASA_CLIENT_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e ASA_TEAM_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e ASA_KEY_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e ASA_PRIVATE_KEY_PATH=/Users/yourname/apple-ads-key-pkcs8.pem \
  -- npx -y apple-ads-mcp

Cursor

添加 .cursor/mcp.json:

{
  "mcpServers": {
    "apple-ads": {
      "command": "npx",
      "args": ["-y", "apple-ads-mcp"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"
      }
    }
  }
}

VS Code

添加到您的 settings.json:

{
  "mcp": {
    "servers": {
      "apple-ads": {
        "command": "npx",
        "args": ["-y", "apple-ads-mcp"],
        "env": {
          "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"
        }
      }
    }
  }
}

Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "apple-ads": {
      "command": "npx",
      "args": ["-y", "apple-ads-mcp"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"
      }
    }
  }
}

Other MCP clients

此服务器使用 STDIO传输任何兼容MCP的客户端都可以通过运行以下命令进行连接：

npx -y apple-ads-mcp

设置这些环境变量：

变量	描述
`ASA_CLIENT_ID`	您的客户ID（以开头 `SEARCHADS.`)
`ASA_TEAM_ID`	您的团队ID（以开头 `SEARCHADS.`)
`ASA_KEY_ID`	您的密钥ID（UUID）
`ASA_PRIVATE_KEY_PATH`	PKCS#8私钥的绝对路径
`ASA_ORG_ID`	（可选）默认使用的组织ID

Inline key (no file)

替换 ASA_PRIVATE_KEY_PATH 随着 ASA_PRIVATE_KEY 并将PEM内容物粘贴 \n 对于换行符：

"ASA_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIGH...your-key...\n-----END PRIVATE KEY-----"

工具

类别	计数	你能做什么
组织	3	列出并在组织之间切换。获取用户详细信息。
活动	6	列出、创建、更新、删除活动。提取绩效报告。
广告组	6	管理广告系列中的广告组。获取广告组报告。
关键词	11	添加/删除目标和负面关键字。更新出价。关键字报告。
搜索词	1	查看人们在点击广告之前搜索的实际查询
广告	7	列出、创建、更新、删除广告。获取广告报告和拒绝原因。
创意作品	5	管理创意和产品页面。
预算订单	4	创建、更新、列出和获取预算订单详细信息。
应用程序和地理	5	搜索符合条件的应用程序，检查资格，查找资产，搜索地理位置。
地理性能	1	按国家/地区划分的绩效明细。
印象分享	3	创建、列出和检索自定义印象分享报告。
优化	2	活动快照和预算利用率分析。

全部54个工具

类别	工具
组织	`list_organizations`, `switch_organization`, `get_me_details`
活动	`list_campaigns`, `get_campaign_details`, `create_campaign`, `update_campaign`, `delete_campaign`, `get_campaign_report`
广告组	`list_ad_groups`, `get_ad_group`, `create_ad_group`, `update_ad_group`, `delete_ad_group`, `get_adgroup_report`
关键词	`get_keyword_report`, `list_targeting_keywords`, `get_targeting_keyword`, `add_targeting_keywords`, `update_targeting_keywords`, `delete_targeting_keywords`, `list_negative_keywords`, `get_negative_keyword`, `add_negative_keywords`, `update_negative_keywords`, `delete_negative_keywords`
搜索词	`get_search_term_report`
广告	`list_ads`, `get_ad`, `create_ad`, `update_ad`, `delete_ad`, `get_ad_report`, `find_ad_rejection_reasons`
创意作品	`list_creatives`, `get_creative`, `create_creative`, `list_product_pages`, `get_product_page_by_id`
预算订单	`list_budget_orders`, `get_budget_order`, `create_budget_order`, `update_budget_order`
应用程序和地理	`search_apps`, `get_app_details`, `get_app_eligibility`, `find_app_assets`, `search_geolocations`
地理性能	`get_geo_performance`
印象分享	`create_impression_share_report`, `get_impression_share_report_by_id`, `list_impression_share_reports`
优化	`get_campaign_snapshot`, `get_budget_analysis`

资源

服务器公开了3个资源：

URI	描述
`apple-ads://countries`	支持Apple搜索广告的国家和地区
`apple-ads://device-sizes`	创意资产的应用程序预览设备尺寸
`apple-ads://metrics-glossary`	所有报告指标（CPA、CPT、TTR等）的定义、公式和基准

提示

6个内置工作流提示，用于指导常见任务：

提示	描述
`campaign_health_check`	全面的活动分析——审查支出、转化率、CPA趋势和标记问题
`keyword_optimization`	关键字和搜索词优化工作流程——发现浪费的支出和新的机会
`new_campaign_setup`	引导新活动创建——浏览应用程序选择、结构、关键字和预算
`budget_reallocation`	跨活动预算分析——确定超支/超支，并提出预算变动建议
`creative_review`	创意A/B评论——比较广告表现，标记拒绝，推荐获奖者
`geo_expansion`	地理扩张分析——对当前市场进行排名，并确定新的进入市场

Troubleshooting

“pkcs8必须是PKCS#8格式的字符串” 您的密钥格式错误。重新运行 openssl pkcs8 命令来自步骤3.

“未选择组织” 使用 list_organizations 然后 switch_organization，或添加 ASA_ORG_ID 到你的配置。

“令牌请求失败（401）” 验证您的 可点击, teamId，以及 keyId 匹配苹果的API标签。检查你是否上传了你的公钥。

“读取私钥失败” 使用绝对路径（例如。 /Users/yourname/...)，不 ~/....

服务器立即断开连接 缺少必需的凭据。你需要这四个： ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID，以及 ASA_PRIVATE_KEY_PATH.

Development

git clone https://github.com/javiergalloroca/AppleAdsMCP.git
cd AppleAdsMCP
npm install
npm run build
npm start

对于热重载： npm run dev

看贡献.md 关于贡献指南。

许可证

麻省理工学院

使用说明

Apple Ads MCP

一览功能

快速开始

设置

步骤1-邀请API用户

步骤2--接受并复制您的凭据

步骤3——生成密钥对

步骤4--将公钥上传到Apple

步骤5--添加到MCP客户端

客户

工具

全部54个工具

资源

提示

许可证

相关 MCP

Flomo笔记服务

LLM营销内容生成工具

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务