AppVisionOS/apple-search-ads-mcp

A Model Context Protocol (MCP) server that wraps the **full Apple Search Ads (now Apple Ads) Campaign Management API v5**. 74 typed tools, 1:1 mapping to every documented v5 endpoint — campaigns, ad groups, ads, creatives, custom product pages, keywords, negative keywords, reports, impression-share reports, budget orders, ACLs, geo/app search, app metadata, rejection-reason audits — plus a raw passthrough for any future endpoints.
> **API lifecycle:** Apple Ads (Search Ads) v5 is the current production API. v5 sunsets January 26, 2027 in favour of the new "Apple Ads Platform API" arriving Summer 2026. This server targets v5.0 → v5.5.
Quick install
Then register with Claude Code in one line:
Setup
1. Get API credentials
The Apple Ads UI splits credentials across two screens. The **API** tab inside Account Settings only manages access for *third-party service providers*; for your own programmatic access, the flow goes through **User Management** first.
a) Invite an API user
In app-ads.apple.com → **Account Settings → User Management → Invite User**:
- Email: any address you control (can be your own; Apple requires a separate Apple ID for the API user)
- Role: pick one with API permissions (e.g. **API Account Manager**)
- Send the invite, then accept it from the invited inbox
b) Generate the key pair locally
While the invite is being processed, generate an ES256 key pair on your machine. **Make sure it's PKCS#8** — Apple's .p8 examples and the older openssl ecparam output are *not* PKCS#8 and jose can't load them.
Keep asa-private.p8 somewhere safe (e.g. ~/.apple-search-ads/, chmod 600). You'll only paste the **public** half into Apple.
c) Generate the API client
Sign out and sign back in **as the invited API user** (not the admin account). Go to **Account Settings → API**. You'll see a **Client Credentials** screen with a *Public Key* textarea — this only appears for users who hold the API role.
1. Paste the contents of asa-public.pem (with the -----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY----- markers).
2. Click **Generate API Client**.
3. Copy the three values Apple shows you: **Client ID**, **Team ID**, **Key ID** — these don't reappear later.
2. Install
3. Configure
Copy .env.example to .env and fill it in, or pass env vars through your MCP client.
ASA_PRIVATE_KEY (PEM contents inline, with \n escapes if injected via JSON) is supported as an alternative to ASA_PRIVATE_KEY_PATH.
4. Wire into your MCP client
Authentication
The server handles OAuth 2.0 client-credentials flow with an ES256 JWT client assertion:
1. Sign a JWT with your .p8 private key (header: kid=Key ID, alg=ES256; payload: iss=Team ID, sub=Client ID, aud=https://appleid.apple.com).
2. POST it to https://appleid.apple.com/auth/oauth2/token with grant_type=client_credentials and scope=searchadsorg.
3. Use the returned 1-hour access token with Authorization: Bearer … and X-AP-Context: orgId=… on every API call.
The token is cached in memory until ~30 s before expiry, so you sign one assertion and exchange one token per hour. On 401 the server force-refreshes and retries once. On 429/5xx it backs off (honouring Retry-After) up to 3 times.
Tool inventory (74 tools)
Account & access (2)
org_acls, me_user — call without an org context to discover what your token can do.
Discovery (3)
search_apps, search_geo, geo_lookup
App metadata (6)
apps_get, apps_locale_details, apps_eligibilities_find, apps_assets_find, creative_app_preview_devices, countries_or_regions_list
Custom Product Pages (3)
cpp_list, cpp_get, cpp_locale_details