The Apple Ads API through MCP

How Apple Ads MCP handles API credentials, ad-account context, reporting dates, money, pagination and controlled writes through the Apple Ads Platform API.

What the MCP server adds

Apple Ads MCP exposes a defined tool set over the Apple Ads Platform API at https://api.ads.apple.com/v1. The client sends a tool name and structured arguments. The server checks the signed-in customer, Apple connection, account access and any required write permission before calling Apple's SDK.

The tool directory is the supported interface. It is not an unrestricted HTTP proxy: an endpoint in Apple's documentation does not automatically become an available MCP tool.

Three separate authorizations

1. Website identity: sign in to manage your connection and support messages.
2. Apple API access: connect your advertising account when account authorization becomes available. The server checks which ad accounts you can access before saving the selected account.
3. MCP client authorization: approve the remote client's OAuth connection to this service.

The connector uses Apple's Node SDK for API access. Saved Apple credentials are encrypted at rest and are not returned in tool results. An Apple authorization with read-only access cannot gain campaign-management rights by enabling this service's spend tier. See Apple's API authentication guide and the account setup instructions.

Ad-account IDs and organization IDs

The connector selects an accessible ad account and uses its ID for account-scoped requests. An organization ID is not interchangeable with that ad-account ID. Start with apple_ads_whoami to inspect the selected account and accessible accounts. Use IDs returned by account discovery rather than copying an illustrative ID from an example.

Dates and attribution

This connector accepts inclusive YYYY-MM-DD dates. Reporting defaults to the previous seven complete days in ORTZ, the ad account's timezone. Search-term reports require ORTZ; other reporting tools also support UTC. Daily, weekly and monthly requests have endpoint-specific date restrictions. An invalid request returns an error instead of silently changing the period.

Total installs, tap-through installs and view-through installs are separate metrics. Period comparisons calculate rates from period totals. A missing field remains null, and a percentage change from a zero baseline remains null. State the dates, timezone and attribution measure when presenting a result.

Money and continuation

Money retains its amount and currency. The numeric _usd sibling is populated for USD values only; it is null for other currencies. The connector does not invent an exchange rate. Budgets and bids are validated in the selected account's currency.

Entity queries and report output are capped at 1000 rows. Entity lists return next_offset; reports can return next.offset and next.metric_offset. Follow the continuation until complete before describing an account total. A capped response is a partial result, not evidence that no more rows exist.

Writes and uncertain outcomes

All advertising mutations require the spend tier with exact confirmation ENABLE SPEND CHANGES. New campaigns and ad groups use manual CPT bidding and start paused; new targeting keywords also start paused. Writes are followed by a readback, and batch operations report per-item outcomes.

An ambiguous transport error is not automatically retried as another write. If a result says the write was accepted but the readback failed, inspect the resource before repeating the operation. Apple no longer supports lifetime campaign budget writes; daily pacing also identifies shared caps it has not evaluated.

Rate limits and recovery

The connector retries an Apple HTTP 429 up to three times, honoring the retry delay when it is within the server's bounded wait. Authentication failures and permission errors need investigation rather than repeated write attempts. Use the troubleshooting guide and account feedback for help.

For direct implementation details, use Apple's API calling guide and the official Node SDK. The integration comparison explains when a hosted tool set fits and when a custom integration may be needed.