Apple Ads Mcp

Name: Apple Ads Mcp
Author: Happygallo

本地服务

github.com/Happygallo其他732 周前更新

代码仓库

关于 Apple Ads Mcp

Apple Ads Mcp 是面向通过 AI 客户端管理 Apple Search Ads 广告系列的营销人员和团队的 MCP 服务。它通过工具、资源和工作流提示词支持广告系列操作、报表、关键词与创意管理，以及组织切换。

主要功能

01管理广告系列和广告组
02管理定向关键词与出价
03查看效果和搜索词报表
04管理创意和预算订单
05在多个组织间切换

适用场景

01查看指定日期范围的广告系列表现
02调整广告系列预算和状态
03查找搜索词并添加匹配关键词
04比较不同组织的广告系列表现

MCP 相关

该服务通过 STDIO 将兼容 MCP 的客户端连接到 Apple Search Ads API v5，提供 54 个工具、3 项资源和 6 个工作流提示词。

#mcp #apple-search-ads #ai-tools #model-context-protocol #apple-ads

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "apple-ads": {
      "command": "npx",
      "args": [
        "-y",
        "apple-ads-mcp"
      ],
      "env": {
        "ASA_CLIENT_ID": "<ASA_CLIENT_ID>",
        "ASA_TEAM_ID": "<ASA_TEAM_ID>",
        "ASA_KEY_ID": "<ASA_KEY_ID>",
        "ASA_PRIVATE_KEY_PATH": "<ASA_PRIVATE_KEY_PATH>",
        "ASA_ORG_ID": "<ASA_ORG_ID>"
      }
    }
  }
}

启动命令npx -y apple-ads-mcp

需要配置的环境变量

ASA_CLIENT_IDApple Search Ads client ID (starts with SEARCHADS.)

ASA_TEAM_IDApple Search Ads team ID (starts with SEARCHADS.)

ASA_KEY_ID密钥Apple Search Ads key ID (UUID)

ASA_PRIVATE_KEY_PATH密钥Absolute path to your PKCS#8 private key file

ASA_ORG_IDOrganization ID (optional, use list_organizations to switch at runtime)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmapple-ads-mcp1.0.3stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Apple Ads MCP

适用于 Apple Search Ads API v5 的 MCP 服务。
将其连接到任意兼容 MCP 的 AI 客户端，即可通过自然语言管理广告系列、关键词、预算和报告。

快速开始 • 工具 • 资源 • 提示词 • 客户端

可以这样向 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标签页
复制并保存以下三个值：
- clientId — 以 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 — 公钥（下一步上传到 Apple）

步骤 4 — 将公钥上传到 Apple

输出公钥：

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

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

前往 searchads.apple.com 上的设置 → API标签页
粘贴到公钥字段
保存

步骤 5 — 添加到你的 MCP 客户端

选择下方的客户端，并填写步骤 2 中的 clientId、teamId 和 keyId，以及步骤 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"
      }
    }
  }
}

其他 MCP 客户端

此服务使用 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

内联密钥（无需文件）

将 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 Search Ads 支持的国家和地区
`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`	地理位置拓展分析——为当前市场排名，并找出可进入的新市场

故障排除

“pkcs8 must be PKCS#8 formatted string” 密钥格式不正确。请重新运行步骤 3中的 openssl pkcs8 命令。

“No organization selected” 请先使用 list_organizations，然后使用 switch_organization；或者将 ASA_ORG_ID 添加到配置中。

“Token request failed (401)” 请确认您的 clientId、teamId 和 keyId 与 Apple API 选项卡中的信息一致。检查是否已上传公钥。

“Failed to read private key” 请使用绝对路径（例如 /Users/yourname/...），不要使用 ~/...。

服务立即断开连接 缺少必需的凭据。您需要全部四项：ASA_CLIENT_ID、ASA_TEAM_ID、ASA_KEY_ID 和 ASA_PRIVATE_KEY_PATH。

开发

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

启用热重载：npm run dev

有关贡献指南，请参阅 CONTRIBUTING.md。

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。