apple-search-ads-mcp 是一个 Model Context Protocol (MCP) 服务器，封装了完整的 Apple Ads（原 Apple Search Ads）Campaign Management API v5。它提供 74 个类型化工具，与 v5 的每一个文档化端点一一对应，包括广告系列、广告组、广告、创意、自定义产品页、关键词、否定关键词、报告、展示份额报告、预算订单、ACL、地理/应用搜索、应用元数据、拒绝原因审核，以及一个用于任何未来端点的原始透传工具。API 生命周期方面，Apple Ads v5 是当前生产 API，将于 2027 年 1 月 26 日停用，取而代之的是 2026 年夏季推出的“Apple Ads Platform API”。本服务器针对 v5.0 至 v5.5。
主要能力分为多个类别：账户与访问（2 个工具：org_acls、me_user）、搜索与地理（search_apps、search_geo、geo_lookup）、应用元数据（6 个）、自定义产品页（3 个）、广告系列（6 个）、广告组（7 个）、创意（4 个：创意包装自定义产品页、默认产品页或创意集引用，广告通过 creativeId 绑定到创意）、广告（7 个）、定位关键词（7 个）、广告组范围否定关键词（6 个）、广告系列范围否定关键词（6 个）、报告（全部接受 startTime、endTime、可选粒度、分组、选择器、返回行总计等）、展示份额报告（3 个，异步）、预算订单（4 个，仅限 LOC 账户）、拒绝原因审核（2 个，只读）、以及一个逃生舱工具 apple_search_ads_request。
使用方式：首先获取 API 凭证。在 app-ads.apple.com 中，通过账户设置 → 用户管理 → 邀请用户，使用具有 API 权限的角色（如 API Account Manager）邀请一个 Apple ID。在邀请处理期间，生成 PKCS#8 格式的 ES256 密钥对，保存私钥（如 ~/.apple-search-ads/asa-private.p8，权限 600），仅将公钥粘贴到 Apple。以受邀的 API 用户身份登录，在账户设置 → API 中粘贴公钥，生成 API 客户端，获取 Client ID、Team ID、Key ID。然后配置 .env 文件或通过 MCP 客户端传递环境变量，支持 ASA_PRIVATE_KEY 或 ASA_PRIVATE_KEY_PATH。最后将服务器接入 MCP 客户端。
服务器处理 OAuth 2.0 客户端凭证流程：使用 .p8 私钥签署 JWT（头部 kid=Key ID，alg=ES256；载荷 iss=Team ID，sub=Client ID，aud=https://appleid.apple.com），POST 到 https://appleid.apple.com/auth/oauth2/token，使用 grant_type=client_credentials 和 scope=searchadsorg，获取 1 小时访问令牌，在每次 API 调用中使用 Authorization: Bearer 和 X-AP-Context: orgId=。令牌缓存到过期前约 30 秒，401 时强制刷新并重试一次，429/5xx 时遵循 Retry-After 退避最多 3 次。
适用场景包括通过 Claude 等 MCP 客户端自动化管理 Apple Ads 广告系列，例如端到端工作流：org_acls 选择组织、search_apps 获取 adamId、创建广告系列、广告组、定位关键词、创建自定义产品页创意并绑定广告、等待后拉取报告、创建展示份额报告等。已知限制：v5 中无旧版创意集 CRUD、无应用类别端点、无邮政编码地理定位、无组织范围关键词查找、预算订单无删除操作、受众/预测/转化事件不在 v5 中。
