andrealufino/aapl-ads-mcp

An MCP server that connects Claude (and any MCP-compatible client) to
Apple Search Ads API v5.
What is this
MCP (Model Context Protocol) is an open standard that lets AI assistants call
external tools. This server implements the MCP stdio transport and exposes 9
read-only tools that query your Apple Search Ads account — campaigns, ad groups,
keywords, and performance reports.
You install it once, point Claude Desktop at it, and then ask questions in plain
English: "Which keywords drove the most installs last month?" or "Show me
campaigns with zero impressions this week."
Why
The official ASA dashboards are good for humans but not for ad-hoc analysis or
automated reporting. Existing MCP alternatives are either SaaS (you hand over
your keys) or unmaintained. This is a self-hosted, open-source option you
control.
Features
- **list_orgs** — verify authentication, list accessible organizations
- **list_campaigns** — enumerate campaigns, optionally filter by status
- **list_ad_groups** — ad groups for a given campaign
- **list_keywords** — targeting keywords with bid amounts and match type
- **get_campaign_report** — impressions, taps, installs, spend, CPI, TTR by campaign
- **get_ad_group_report** — same metrics broken down by ad group
- **get_keyword_report** — per-keyword performance with weekly/daily/monthly granularity
- **get_search_terms_report** — the real search queries that triggered your ads (most useful for discovery)
All tools default to the last 30 days. Reports support HOURLY, DAILY,
WEEKLY, and MONTHLY granularity.
Limitations
- **Read-only by design.** No write operations (create, update, pause) in this release.
- **Requires Apple Search Ads Campaign Management API access.** You need to create an API user in your ASA account and generate an ES256 key pair.
- **Aggregate install metrics work without app-side integration.** tapInstalls, viewInstalls, and related fields in ASA reports are populated by Apple Search Ads directly and do not require any SDK in your app. AdServices / AdAttributionKitis only needed if you want to attribute installs to specific campaigns from inside your app (e.g. for onboarding personalization).
- **Single organization.** The org ID is fixed in the config. Multi-org switching is not implemented.
Setup
1. Generate an ES256 key pair
Use the modern genpkey command — it produces PKCS#8 format directly, which is what this server requires. The older ecparam -genkey produces SEC1 format and will cause a startup error.
Verify the private key starts with -----BEGIN PRIVATE KEY----- (not -----BEGIN EC PRIVATE KEY-----). If it starts with the EC variant, convert it:
Store private-key.pem outside the repository root if possible (e.g. ~/.ssh/asa-private-key.pem).
2. Create an API user in Apple Search Ads
1. Go to **ASA → Account Settings → User Management**
2. Click **Create User**, choose role **API Account Read Only** for read-only usage (recommended for this server). **API Campaign Manager** is also fine and adds write permissions if you plan to extend the server with write tools later.