内容
aapl-ads-mcp
[](https://nodejs.org)
[](LICENSE)
[](https://glama.ai/mcp/servers/andrealufino/aapl-ads-mcp)
一个连接 Claude（以及任何支持 MCP 的客户端）到 [Apple 搜索广告 API v5](https://developer.apple.com/documentation/apple_search_ads) 的 MCP 服务器。
##项目
MCP（模型上下文协议）是一种开放标准，允许 AI 助手调用外部工具。该 MCP 的 stdio 传输协议，并暴露了 9 个只，用于查询您的 Apple 搜索广告账户 — 活动、广告组、关键词和性能报告。
您只需安装一次，并将 Claude Desktop 指向它，然后用纯英文提问：“哪些关键词在上个月带来了最多的安装？”或“显示本周没有展示的活动。”
## 为什么
官方 仪表板对人类来说很好，但不适合临时分析和自动化现有的 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** — 获取触发您广告的实际搜索查询适合发现）
- **get_ad_group_report** — 获取广告面的相同指标
所有工具默认 30 天的数据。报告支持 `HOURLY`、`DAILY`、`WEEK 和 `MONTHLY` 粒度。
## 限制
设计为只读。** 本写入操作（创建、更新、暂停）。
- **需要 Apple 搜索广告活动管理 API 访问权限。** 您需要在 ASA 账户中创建 API 用户并生成 ES256 密钥对。
- **聚合安装指标无需应用侧集成即可** ASA 报告中的 `tapInstalls`、`viewInstall 和相关字段由 Apple 搜索广告直接填充，不需要在您的集成任何 SDK。AdServices / [AdAttributionKit](https://developer.apple.com/documentation/adattributionkit) 仅在您想将安装归因于应用内的特定活动时需要（例如，用于 onboarding 个性化）。
- **单个组织。** 组织 ID 在配置文件中固定。未实现多组织切换。
## 设置
### 1. 生成 ES256 密钥对
使用现代的 `genpkey` 命令 — 它直接生成 PKCS#8 格式，这是本服务器要求的格式。较旧的 `ecparam -genkey` 命令生成 SEC1 格式，会导致启动错误。
```bash
# 生成私钥（PKCS#8）
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem
# 导出公钥
openssl pkey -in private-key.pem -pubout -out public-key.pem
```
验证私钥是否以 `-----BEGIN PRIVATE KEY-----` 开头（而不是 `-----BEGIN EC PRIVATE KEY-----`）。如果以 EC 变体开头，请转换它：
```bash
openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem
```
将 `private-key.pem` 存储在存储库根目录之外（例如 `~/.ssh/asa-private-key.pem`）。
### 2. 在 Apple 搜索广告中创建 API 用户
1. 进入 **ASA → 账户设置 → 用户管理**
2. 点击 **创建用户**，选择角色 **API 账户只读** 进行只读使用（建议使用本服务器）。**API 活动管理器** 也可以，并为以后扩展服务器添加写入权限。
3. 进入 **API** 标签页，点击 **创建客户端**
4. 上传 `public-key.pem`
5. 从确认屏幕复制 `client_id`、`team_id` 和 `key_id`
6. 在 **账户设置 → 概览** 中查找您的 `org_id`
### 3. 克隆并构建
```bash
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`:
```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` 优先。
Desktop。询问“运行健康检查”以验证服务器是否。
## 使用示例
使用 Claude Desktop 运行服务器时有效的提示：
```
我的 Apple 广告活动```
```
显示最近 的活动表现
```
```
活动中哪些关键词在上安装？
```
```
过去一个月词触发了我的广告？重点关注那些有展示但无安装的词。
```
2025 年第一季度所有花费
```
```
1234567890组及其出价金额## 开发
```bash
npm run build # 编译 TypeScript
npm test # 运行测试套件（Vitest）
npm run typecheck # 类型检查（不生成输出）
npm run lint # Biome lint
npm run format # Biome（写入）
```
### MCP 检验工具
在没有 的情况下交互式调试：
```bash
@modelcontextprotocol/inspector/index.js
```
在连接之前，在 Inspector UI 中设置。
### 预提交钩子
在克隆后安装 lefthook 钩子：
```bash
npx lefthook install
```
这会设置：
- `gitleaks protect --staged` — 阻止密的提交
- 对暂存的 `.ts` 文件进行 Biome lint 检查
- TypeScript 类型检查
## 贡献
参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 获取技术细节：身份验证流程、HTTP 客户端设计、工具模式、报告模式怪癖和 ASA v5 开发经验教训。
欢迎提交错误报告和拉取请求。
## 安全
- 永远不要提交 `.env` 或 `*.pem` 文件 — 两 `.gitignore` 中
- 将 `private-key.pem` 保存在存储库根目录之外 访问令牌仅保存在内存中，永远不会
- 如果您怀疑密钥已泄露，请在 **ASA → 账户设置 → API** 中轮换它
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
