apple-ads-mcp

# Apple Ads MCP

[![CI](https://github.com/zelentsov-dev/apple-ads-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zelentsov-dev/apple-ads-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/zelentsov-dev/apple-ads-mcp)](https://github.com/zelentsov-dev/apple-ads-mcp/releases)
[![Go](https://img.shields.io/badge/Go-1.26.9%2B-00ADD8?logo=go)](go.mod)
[![License](https://img.shields.io/github/license/zelentsov-dev/apple-ads-mcp)](LICENSE)

Apple Ads MCP is a local-first [Model Context Protocol](https://modelcontextprotocol.io/) server for the [Apple Ads Platform API v1](https://developer.apple.com/documentation/apple-ads-platform-api). It gives Codex, Claude, and other MCP clients typed tools to research, inspect, and safely operate App Store advertising accounts.

The server is read-only by default. Credentials stay on your machine, every account-scoped call names an explicit profile and ad account, and every mutation requires a preview plus a short-lived single-use receipt.

Apple Ads MCP is independent open-source software. It is not affiliated with, endorsed by, or sponsored by Apple Inc. Apple Ads and App Store are trademarks of Apple Inc.

## Quick start

Install the released binary with Homebrew on macOS or Linux:

```bash
brew install zelentsov-dev/tap/apple-ads-mcp
apple-ads-mcp version
```

Create a local read-only profile. The command stores an absolute private-key path; never paste the private key into a chat, issue, log, or repository:

```bash
apple-ads-mcp config init
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only
```

Register the server with an absolute Homebrew path so desktop apps and IDE extensions do not depend on their inherited shell `PATH`.

Codex:

```bash
codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list
```

Claude Code:

```bash
claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads
```

Restart an already running desktop app, CLI session, or IDE extension, then start a new conversation. A safe first request is:

> Call `server_info`, then run `account_health` for my explicit profile, ad account, and app. Do not enable writes.

Other useful read-only starters:

- “List the apps I can advertise and explain any eligibility gaps.”
- “Audit my current Apple Ads campaign structure without changing anything.”
- “Find keyword opportunities and separate Apple evidence from your inferences.”

## Current release

`v0.3.7` is the current release. It honors Apple rate-limit timing, validates bid strategies in their campaign and ad-group context, updates report grouping, and deprecates CPA cap without removing existing tools. Explicit strategy requests and optimizer recommendations now have separate history policies. See the [v0.3.7 release and migration notes](docs/MIGRATION-v0.3.7.md).

The v0.3.5 version-final archive naming, formula-scoped trust from v0.3.4, exact-path verification from v0.3.3, and one-command onboarding from v0.3.2 remain intact.

Optimization is never autonomous: the server has no scheduler and never changes spend in the background. A read-only session can build a baseline and plan. Applying a plan still requires every write gate, an active named policy, one receipt, a fresh report and inventory drift check, and item-level verification.

The release supports the four App Store placements exposed by Apple:

- Search Results
- Search Tab
- Today Tab
- Product Pages

Placement availability still depends on the selected account, app, storefront, creative, and Apple's eligibility response. An unavailable placement is reported as `not_eligible`; the server does not attempt to bypass Apple validation.

Keywords and negative keywords are Search Results resources. The Platform API rejects explicit `Ad` resources for Search Results campaigns, so that placement is operated through its campaign, ad group, keywords, and product-page configuration; explicit ads remain eligibility-gated for the other placements. A Default Product Page creative is unique per app and ad account, so operators should query and reuse it instead of attempting to create a duplicate.

## What it can do

| Area | Main tools |
| --- | --- |
| Access and readiness | `auth_check`, `ad_accounts_list`, `ad_account_get`, `advertiser_resources_list`, `account_health` |
| Apps and storefronts | `apps_search`, `apps_get`, `apps_eligibility`, `app_locale_details`, `supported_app_languages`, `app_store_geo_search` |
| Inventory | `campaigns_query`, `ad_groups_query`, `keywords_query`, `negative_keywords_query`, `ads_query`, `creatives_query`, `shared_budgets_query`, `campaign_inventory` |
| Diagnostics | rejection reasons, campaign status reasons, change history, account and campaign audits |
| Research | keyword, phrase, category, target-CPA suggestions, search popularity, impression share |
| Reports | typed campaign, ad-group, ad, keyword, and search-term reports |
| Campaign operation | create/update, budget, countries, schedule, pause, and resume previews |
| Ad-group operation | create/update, schedule, targeting, Search Match, bid, deprecated CPA cap, pause, and resume previews |
| Keywords | individual and bulk targeting/negative keyword create/update, bid, pause, and resume previews |
| Ads and creatives | typed App Store creative and ad create/update, pause, and resume previews |
| Recommendations | read, apply-preview, and dismiss-preview for daily budget and target CPA |
| Optimization | named local policies, 28-day baselines, learning/active plans, composite preview/apply/verify, and bounded history |
| Shared budgets | typed LOC-only create/update/assign/unassign previews with private local billing profiles |
| Lifecycle | separately gated campaign, ad-group, keyword, negative-keyword, ad, creative, and shared-budget delete previews |
| Verification | `operations_inspect`, `operations_apply`, `operations_verify`, and direct resource readback |

Every list is bounded to 200 items and uses `next` pagination. Responses include concise text plus MCP `structuredContent`; raw Apple envelopes and billing contact PII are not exposed.

There is no raw-request tool, account/delegation mutation, automatic scheduler, Apple Maps surface, or legacy Campaign Management API v5 support.

## Safety model

A write is possible only when all gates pass:

1. The Apple API user has a compatible write role.
2. The server starts with `--allow-writes`.
3. The selected profile has `allowWrites: true`.
4. A specialized `*_preview` tool validates the account, app, storefront, placement, currency, and payload.
5. `operations_apply` receives the same unexpired receipt.
6. The affected inventory still matches the state captured during preview.

Preview receipts expire after ten minutes and are single-use for apply. A bounded tombstone preserves the explicit expired state after the full receipt record is pruned. Every mutation receipt binds canonical object scopes for its target IDs and retains exact read fingerprints; creates and parent deletes also bind the affected inventory and bounded cascade scopes. Generic, bulk, delete, recommendation, shared-budget, and optimization verification shapes for overlapping objects therefore cannot dispatch concurrently. Independent ad-group inventories remain parallel. Bulk receipts return item-level `applied`, `failed`, or `unknown` states. One targeting-keyword bulk receipt may contain multiple per-item ad groups while still sending one Apple bulk request. Apple may partially accept a batch; the server never promises rollback. If an optimization apply has an unresolved outcome, a sanitized recovery recipe remains in owner-only local history so `operations_verify` can reconcile the supplied receipt after a process restart or normal preview eviction.

Independent previews from the same inventory snapshot intentionally drift after the first apply. Put related keyword creates into one bulk preview when they must be applied as a unit; the server does not weaken this fail-closed invariant.

Mutation requests are not retried after a timeout. The result is `committed_unverified`, or item-level `unknown`, until `operations_verify` and direct readback establish the actual state.

Recommendation apply operations require an explicit `maximumAmount`. The recommendation currency must match the ad account, the proposed amount must stay under the cap, and the recommendation plus promoted campaign are re-read before apply.

An irreversible delete has five additional gates: `--allow-deletes`, profile `allowDeletes: true`, session-only `APPLE_ADS_ALLOW_DELETES=true`, an exact expected object name or keyword text, and a specialized delete receipt. Campaigns and parents must be `PAUSED`; cascade inventory is bounded and hashed; creatives must have no referencing ads; shared budgets must have no assignments. DELETE is never retried after an ambiguous result.

## Release validation

The v0.3.7 release requires the complete compatibility suite, MCP stdio contract tests, unit and HTTP tests, the race detector, static analysis, vulnerability and secret scans, and distribution validation. Cross-platform CI runs on macOS, Linux, and Windows.

This release uses synthetic acceptance only; no live advertising mutations are part of v0.3.7 validation. Runtime confirmation is a separate owner-controlled gate. On 2026-08-31, the v0.3.6 P2 read-only matrix and a separately authorized `PAUSED` targeting-keyword bulk fixture with 2 and 28 items passed against Apple Ads API v1. Both aggregate receipts applied and verified every returned keyword ID directly; the campaign and ad group remained `PAUSED` throughout the write acceptance.

Earlier v0.3.x live acceptance confirmed read-only optimization baselines and plans, `PAUSED` fixture creation and readback, budget/bid/strategy updates, pause/resume, receipt drift checks, item v