Apple Ads via MCP

The MCP server provides three Apple Ads read tools and separate campaign-management tools. This page explains their metrics, access requirements, and limitations.

​

The tools

​

Reading the report

get_apple_ads_report returns one row per entity at the requested level, each carrying a qonversion block (cohort outcomes), an apple block (spend and delivery), and derived ratios.

​

Choose a cohort-window mode

Row-level revenue/roas are cumulative to date: revenue keeps accruing while spend is bounded by the period, so they cannot compare cohorts of different ages. Request windows (d0, d7, d30, … lifetime) to add cohort-window metrics, and set windows_mode explicitly when the reading matters:

• mature includes only fully matured install dates and uses the spend of the closed dates.
• growing includes all installs in the selected period, counts outcomes observed so far up to each window’s boundary, and uses the row’s Apple spend for that period.

If you omit windows_mode, check meta.windows.mode for the reading served; when it is absent, the response uses the mature reading. These post-install outcome windows are separate from Apple’s ad-to-download attribution window. The closure rules below describe windows_mode=mature:

• is_closed: false means the numbers cover a closed subrange — [closed_from, closed_through], not [from, to]. They are provisional, and the ratios can move in either direction. Say the window is still maturing and name closed_through.
• d0 means through the end of the install UTC day, not the first 24 hours from the install moment.
• lifetime never closes, by definition.
• null is not zero. A missing ratio means “not available yet”; a spend_closed: 0 is a measured zero.
• A date is final only once it is past both the window length plus the buffer and meta.windows.spend_snapshot.rewrite_days_effective — the number of recent days whose spend Apple can still restate; those dates are not treated as closed.

​

Markers to check before quoting anything

apple is null for rows without Apple data; partial_sources lists Apple data sources not included (empty when complete); meta.partial_scope counts campaigns without Apple data. Qonversion metrics are always complete. meta.is_partial_period is true when the range includes a UTC day that has not ended, meta.windows.spend_snapshot describes the spend data behind the windows, and meta.request.filters_applied lists the filters applied to the response — check it before assuming a filter took effect.

​

Reading the series

get_apple_ads_series plots one metric per UTC day. The MCP series tool accepts one metric per call, selected with metric: spend, installs, taps, users, trials, trials_converted, paying, revenue, arpu, arppu, roas, or cost_per_subscription. The default is spend. It does not expose REST’s metrics list or window metric names. Make separate calls for multiple metrics, or use REST API v4, which accepts up to four metrics per request.

• value: null means no value is available for that day (for example, a day outside coverage, or an empty denominator); it is never zero.
• is_cohort_metric: true means the point belongs to the cohort acquired that day — revenue on 3 March is “what the people acquired on 3 March have paid to date”, not revenue collected on 3 March.
• filters_ignored lists filters that were accepted and not applied (the entity-state filters have no meaning on a time axis). Non-empty means your numbers answer a wider question than you asked.

​

Checking the connection

Call get_apple_ads_connection_status before drawing conclusions from an empty report: it shows whether reporting is available and what to do next. The reporting field shows whether performance data can flow: ready, verifying or not_ready. States worth naming precisely: The response never contains a private key, client secret, token, authorization code or OAuth state — and the tool cannot start the sign-in flow. It returns dashboard_url instead, which is where a human completes it. Never paste a .p8 key or a client secret into a chat.

​

Manage campaigns

Campaign-management tools require the separate apple_ads:write scope, the acting user’s Manage Apple Ads campaigns permission, and Apple authorization that allows the change. Read access does not grant write access. Provide the current before_status, before_bid, or before_daily_budget value from the report. Bid and budget amounts are decimal strings in the advertising account’s currency. dry_run: true simulates the change. Reuse the same idempotency_key when retrying the same attempt. Pausing or lowering a bid or budget executes directly. Enabling an entity or increasing a bid or budget requires human confirmation through confirm_destructive_action. The same per-project limits apply: daily limits use a rolling 24 hours, and each change stops counting 24 hours after it was made.

​

Understand tool limitations and errors

• Shared Apple account: spend splitting by app across projects is being rolled out. Do not assume a shared account’s spend is already isolated to each project’s app.
• Product filters: product filtering is unavailable for window ROAS/CAC. The public API refuses filter[product_id]; remove it from window requests.
• REST-only parameters: MCP does not expose the series metrics list or the report’s metric_filters thresholds. Use the public API for those parameters.

Apple Ads read tools preserve unsupported_filter_for_window_metrics and unsupported_parameter in their error messages. The first identifies an unsupported product/window combination; the second identifies an unsupported parameter. Change the request before retrying. A null value is unavailable data, never a measured zero.

​

Rate limits

The report and series tools are rate limited. A 429 response includes Retry-After; wait that long before retrying.