apple-search-ads-mcp is a Model Context Protocol (MCP) server that wraps the complete Apple Ads (formerly Apple Search Ads) Campaign Management API v5. It provides 74 typed tools, corresponding one-to-one with every documented endpoint in v5, including campaigns, ad groups, ads, creatives, custom product pages, keywords, negative keywords, reports, share-of-voice reports, budget orders, ACLs, geo/app search, app metadata, rejection reason review, and one raw passthrough tool for any future endpoints. Regarding the API lifecycle, Apple Ads v5 is the current production API and will be deprecated on January 26, 2027, to be replaced by the "Apple Ads Platform API" launching in summer 2026. This server targets v5.0 through v5.5.
Main capabilities are divided into several categories: account and access (2 tools: org_acls, me_user), search and geo (search_apps, search_geo, geo_lookup), app metadata (6), custom product pages (3), campaigns (6), ad groups (7), creatives (4: creative wrapping a custom product page, default product page, or creative set reference; ads are bound to creatives via creativeId), ads (7), targeting keywords (7), ad group-scoped negative keywords (6), campaign-scoped negative keywords (6), reports (all accept startTime, endTime, optional granularity, grouping, selectors, returned row totals, etc.), share-of-voice reports (3, asynchronous), budget orders (4, LOC accounts only), rejection reason review (2, read-only), and one escape hatch tool apple_search_ads_request.
How to use: First obtain API credentials. In app-ads.apple.com, via Account Settings → User Management → Invite User, invite an Apple ID using a role with API permissions (such as API Account Manager). During invitation processing, generate an ES256 key pair in PKCS#8 format, save the private key (such as ~/.apple-search-ads/asa-private.p8, permissions 600), and paste only the public key into Apple. Log in as the invited API user, paste the public key in Account Settings → API, generate an API client, and obtain the Client ID, Team ID, and Key ID. Then configure the .env file or pass environment variables through the MCP client, supporting ASA_PRIVATE_KEY or ASA_PRIVATE_KEY_PATH. Finally, connect the server to the MCP client.
The server handles the OAuth 2.0 client credentials flow: sign a JWT with the .p8 private key (header kid=Key ID, alg=ES256; payload iss=Team ID, sub=Client ID, aud=https://appleid.apple.com），POST to https://appleid.apple.com/auth/oauth2/token，使用 grant_type=client_credentials and scope=searchadsorg, obtain a 1-hour access token, and use Authorization: Bearer and X-AP-Context: orgId= in every API call. Tokens are cached until about 30 seconds before expiration, forcibly refreshed on 401 with one retry, and on 429/5xx follow Retry-After backoff up to 3 times.
Applicable scenarios include automating Apple Ads campaign management through MCP clients such as Claude, for example end-to-end workflows: org_acls to select an organization, search_apps to obtain the adamId, create a campaign, ad group, and targeting keywords, create a custom product page creative and bind an ad, pull reports after waiting, create a share-of-voice report, etc. Known limitations: no legacy creative set CRUD in v5, no app category endpoint, no postal code geolocation, no organization-wide keyword lookup, no delete operation for budget orders, and audiences/forecasting/conversion events are not in v5.
