Apple Ads MCP
Apple Ads MCP is a local-first Model Context Protocol server for the Apple Ads Platform API v1. 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:
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:
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:
codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list
Claude Code:
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 runaccount_healthfor 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.8 is the current release. It aligns campaign and ad-group bidStrategy.bid schemas and runtime validation with Apple Ads Platform API v1 (TargetCpa on campaigns versus default Max CPT on ad groups), explicitly sends "bid": null when switching a campaign to MANUAL_CPT so Apple clears any prior TargetCpa, and normalizes decimal money strings in operations_verify. See the v0.3.8 release and migration notes.
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
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:
- The Apple API user has a compatible write role.
- The server starts with
--allow-writes. - The selected profile has
allowWrites: true. - A specialized
*_previewtool validates the account, app, storefront, placement, currency, and payload. operations_applyreceives the same unexpired receipt.- 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.8 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 in CI; runtime confirmation against live Apple Ads API v1 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 verification, and deletion of disposable campaigns, ad groups, keywords, and negative keywords. All retained fixtures remained PAUSED with zero spend.
Account-dependent paths have an explicit evidence boundary:
- Active optimization-plan apply and
MAX_CONVERSIONSchanges remain automated-test verified for this release. Optimizer recommendations require the existing history minimums; explicit user-requested previews instead show a warning that statistical readiness has not been established, while preserving contract validation and write gates. - Shared-budget create/update/assignment/delete remain contract- and HTTP-test verified because the live acceptance account uses
PAYG; Apple requiresLOC. - Default Product Page ad and creative deletion is confirmed as
not_eligiblebecause Apple does not allow those resources to be deleted individually.
These boundaries do not weaken the default safety model: unsupported or insufficiently evidenced operations fail closed and never become successful empty responses.
Install
Homebrew
The official tap installs a checksum-pinned release binary:
brew install zelentsov-dev/tap/apple-ads-mcp
Upgrade later releases with:
brew update
brew upgrade apple-ads-mcp
GitHub release
Download the archive for your platform from GitHub Releases. Releases include SHA-256 checksums and SPDX SBOMs.
Apple silicon example:
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp
Windows users should verify checksums.txt, extract the matching ZIP, and register the executable with its absolute path.
OCI image
docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.3.8
The image runs serve --stdio by default. Mount accounts.json and its referenced private key read-only.
Build from source
git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./apple-ads-mcp ./cmd/apple-ads-mcp
Go 1.26.10 or newer is required.
Apple API setup
Apple Ads API access is separate from App Store Connect access. An Apple Ads Account Admin must add an API user with the appropriate role. Prefer API Account Read Only until campaign changes are needed.
Generate an ES256 key pair locally:
umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem
Upload only the public key in Apple Ads. Never paste the private key into an agent conversation, issue, log, or repository. After Apple registers the key, record the client ID, team ID, and key ID shown in the Apple Ads UI.
Configure
Create a profile interactively:
apple-ads-mcp config init
The default configuration path is ~/.config/apple-ads-mcp/accounts.json:
{
"profiles": [
{
"name": "production-read-only",
"clientId": "SEARCHADS.example-client-id",
"teamId": "SEARCHADS.example-team-id",
"keyId": "EXAMPLEKEY",
"privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
"defaultAdAccountId": "123456789",
"allowWrites": false,
"allowDeletes": false
}
]
}
On POSIX systems, the configuration and private key must be owner-only:
chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem
Validate authentication and discover accessible ad accounts:
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only
Configuration precedence is --config, APPLE_ADS_MCP_CONFIG, the default file, then single-profile APPLE_ADS_* environment variables. Supported single-profile variables are APPLE_ADS_PROFILE, APPLE_ADS_CLIENT_ID, APPLE_ADS_TEAM_ID, APPLE_ADS_KEY_ID, APPLE_ADS_PRIVATE_KEY_PATH, APPLE_ADS_AD_ACCOUNT_ID, APPLE_ADS_ALLOW_WRITES, and APPLE_ADS_ALLOW_DELETES. For a file-backed profile, environment variables do not silently grant persistent write or delete permission.
Connect an MCP client
The server uses stdio and writes MCP JSON-RPC only to stdout:
apple-ads-mcp serve --stdio
For clients with a CLI, prefer an absolute binary path.
Codex global configuration:
codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list
Codex Desktop, the Codex CLI, and the IDE extension share the same host configuration. Restart an already running client and open a new conversation after adding the server.
Claude Code user configuration:
claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads
Claude project configuration can use the repository's .mcp.json, but each workspace/server may remain pending until the user approves it. Reconnect from /mcp or restart Claude Code after approval.
Generic MCP configuration for clients without a registration command:
{
"mcpServers": {
"apple-ads": {
"command": "apple-ads-mcp",
"args": ["serve", "--stdio"]
}
}
}
Replace apple-ads-mcp with the absolute executable path when the client does not inherit the Homebrew or shell PATH. On Apple silicon the default Homebrew path is /opt/homebrew/bin/apple-ads-mcp; on Intel macOS it is normally /usr/local/bin/apple-ads-mcp.
Plugin and skill bundle
Release archives include .codex-plugin/plugin.json, .mcp.json, and the apple-ads-operator skill. These files describe the server and safe operating workflow for compatible plugin loaders, but they do not install the executable, register the MCP server, or grant Apple Ads access by themselves. This repository is not currently distributed through a public Codex plugin marketplace; Homebrew plus client registration is the supported public setup path.
Verify the connection
After restarting the client, confirm that apple-ads is enabled or connected and ask it to call server_info. After local credentials are ready, use the explicit profile and account for auth_check, ad_accounts_list, and account_health.
All setup verification must remain read-only. Do not add --allow-writes, --allow-deletes, allowWrites, or allowDeletes while troubleshooting installation or authentication.
Troubleshooting
- Executable not found: use
"$(brew --prefix)/bin/apple-ads-mcp"in the client configuration instead of a bare command. - Server already exists: remove only that client's existing
apple-adsentry, then add it again with the absolute path. - Claude shows pending approval: approve the project MCP server, reconnect from
/mcp, and start a new conversation. - A running client still lacks tools: fully restart the desktop app, CLI session, or IDE extension after changing MCP configuration.
- Authentication fails: run
apple-ads-mcp auth doctor --profile <profile>locally and confirm file permissions and non-secret identifiers; never paste the private key into chat. - Homebrew rejects a downloaded local formula: install from the trusted tap with
brew install zelentsov-dev/tap/apple-ads-mcp.
Agent-led setup
An agent may diagnose and perform installation only with the user's approval. It should verify the binary, use an absolute path, register the intended client scope, restart the client, and stop after read-only health checks. It must never request private-key contents or silently enable mutation gates.
Enable writes for one session
Keep persistent profiles read-only. For one explicitly authorized operator session, enable both local gates:
APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes
This does not change anything by itself. Every mutation still needs explicit profile, adAccountId, a specialized preview, receipt apply, and verification.
Configure on-demand optimization
Create a named local policy:
apple-ads-mcp optimization policy init
apple-ads-mcp optimization policy validate --name mature-product-balanced
apple-ads-mcp optimization doctor --policy mature-product-balanced
Policies are stored in ~/.config/apple-ads-mcp/optimization-policies.json with mode 0600. Each policy binds one profile, one ad account, one promoted app, and at most 20 campaign IDs. learning mode requires no business target and only returns evidence. active mode requires targetInstallCPA, total and per-campaign daily-budget caps, and explicit permissions for budget, bid, strategy, pause, resume, and retest. A policy that allows bid changes must also set a positive, account-currency maxBid; the daily-budget cap is never reused as a bid cap.
The balanced preset requires exactly 28 unique consecutive completed UTC days ending yesterday, compares the latest 7 days with the previous 7, applies a 72-hour cooldown, normally proposes 10% changes, and never exceeds 20% per run. Missing, duplicate, future, malformed, or overflowing report evidence fails closed. It can propose MAX_CONVERSIONS only for eligible Search Results Search Match inventory averaging at least five tap installs per day over 14 days. It never proposes deletion.
Typical agent flow:
- Call
optimization_baselineandoptimization_planin a read-only server. - Review Apple recommendations separately from calculated actions.
- Start an authorized write session and call
optimization_plan_preview. - Inspect
OperationImpact, apply the same receipt once, then calloperations_verify. - Review bounded local history under
~/.local/share/apple-ads-mcp/optimization/.
Immediately before the first Apple write, the server durably persists a receipt-hash-bound applying intent and sanitized typed verification recipe under an inter-process file lock. POSIX commits sync the containing directory; Windows uses replace-with-write-through semantics. An unknown result, inconclusive verification, or interrupted history update blocks later optimization plans until operations_verify conclusively reconciles every affected item. Recovery survives process restart and normal in-memory receipt expiry, but requires the original opaque receipt from the operator. A reconciled matched or matched_after action starts cooldown from its original intent/apply time; matched_before does not. A campaign can be auto-resumed only when a verified optimizer-owned pause still has the same Apple modificationTime; any later manual change revokes that permission. No receipt, credential, raw Apple envelope, or billing contact is stored in optimization history.
Shared budgets and lifecycle operations
Shared-budget mutations are available only when Apple reports the account payment model as LOC. Create and update operations bind the budget exclusively to the explicitly selected ad account. Campaign assignment tools preserve unrelated existing assignments, and cross-account shared budgets fail closed. Initialize private billing data locally:
apple-ads-mcp billing profile init
~/.config/apple-ads-mcp/billing-profiles.json must be 0600. MCP inputs contain only the local billingProfile name. Buyer names and email addresses are not returned in tool output, logs, history, or receipt previews. PAYG accounts return not_eligible without attempting a write.
For an explicitly authorized destructive maintenance session:
APPLE_ADS_ALLOW_WRITES=true \
APPLE_ADS_ALLOW_DELETES=true \
apple-ads-mcp serve --stdio --allow-writes --allow-deletes
The selected file-backed profile must already contain allowDeletes: true; allowWrites may be enabled for only the current process with APPLE_ADS_ALLOW_WRITES=true. The server and session delete gates remain independent. Use a specialized *_delete_preview, compare the full cascade impact and exact expected text, apply once, and verify deleted: true. Do not use lifecycle operations as part of an optimization plan.
Operational limits
- Apple provides no public Ads API sandbox. Live mutation acceptance is manual, explicitly enabled, uses clearly named
PAUSEDfixtures, and is never part of automatic CI. - Eligibility, suggestions, popularity, recommendations, reports, and creative support vary by account and storefront.
- Cold accounts may have no target-CPA or daily-budget recommendations.
- Campaign and object names are validated by Apple; the web UI and API may accept different punctuation.
- Apple rejects the vertical-bar character (
|) in campaign names; use a hyphenated readable name instead. Ad-group creation requires an ISO 8601startTimein the ad-account timezone. - Reports can lag and remain empty until delivery occurs.
- Apple rejects individual deletion of an ad that uses the Default Product Page (
CAN_NOT_DELETE_DPP_CREATIVE_AD). The server returnsnot_eligibleduring preview; use lifecycle deletion only for disposable Custom Product Page ads and creatives. - Trial and subscription attribution belongs to your attribution stack; the Apple Ads Platform API alone does not prove keyword-to-trial attribution.
Known Apple API responses
As of 2026-08-25, the documented v1 request shapes used by this server have produced two repeatable upstream behaviors during live acceptance:
phrase_suggestionsandcategory_suggestionsmay return Apple HTTP500for aSUGGESTIONquery even whenkeyword_suggestionsandtarget_cpa_suggestionswork for the same owned app.impression_sharemay return Apple HTTP400on a cold or fully paused account. An owner-controlled acceptance account supplied no code or diagnostic details; public reproductions have also reported codeINVALID_VALUE. Missing recent delivery may be relevant, but it is not a confirmed Apple prerequisite or workaround.
The server returns these as bounded structured Apple errors and does not convert them into empty or successful results. Safe Apple code, message, and detail fields are retained for 4xx; request bodies, credentials, arbitrary fields, and 5xx bodies are not returned. The request shapes match the current Apple Ads Platform API and the official Apple Java client. Comparable public v1 reproductions are recorded in App Store Connect CLI PR #2057 and PR #2020. Recheck after Apple changes the API or the account has meaningful delivery history.
Compatibility
v0.3 preserves all v0.2.1 tool names and schemas, then adds optimization, shared-budget mutation, bid-strategy, and lifecycle tools. v0.3.1 adds a required maxBid when bid permission is enabled and fail-closed reconciliation rules; see the v0.3.1 migration notes. v0.3.2 changes distribution and onboarding only. v0.3.3 switches release verification to the exact tap formula path, v0.3.4 adds formula-scoped trust for Homebrew 6, and v0.3.5 disambiguates Homebrew version detection by placing the semantic version at the end of archive names. v0.3.6 keeps existing tool names and compatible legacy inputs while adding typed aliases, query shortcuts, diagnostics, and stricter required scopes; see the v0.3.6 notes. v0.3.7 adds header-aware request pacing, contextual bid validation, report grouping corrections, and persisted preview warnings; see the v0.3.7 notes. v0.3.8 separates campaign and ad-group bidStrategy.bid requirements, clears TargetCpa with "bid": null when switching campaigns to MANUAL_CPT, and normalizes decimal money strings in operations_verify; see the v0.3.8 notes. Older clients should also read the v0.3 notes and v0.2 notes.
The public tool schema is not frozen before v1.0. API-family scope and operation status are tracked in the machine-readable operation matrix. The official Java client baseline and App Store endpoint inventory are tracked in upstream-baseline.json.
Development
gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run honnef.co/go/tools/cmd/[email protected] -checks 'all,-ST1000,-ST1005' ./...
go run golang.org/x/vuln/cmd/[email protected] ./...
go run github.com/zricethezav/gitleaks/[email protected] dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/[email protected] check
go run github.com/rhysd/actionlint/cmd/[email protected]
npx --yes [email protected] '**/*.md'
python3 scripts/validate_distribution.py
python3 scripts/audit_upstream.py
See CONTRIBUTING.md, SECURITY.md, and the roadmap.