Local Apple Ads research, reports, and receipt-gated campaign management.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
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:
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:
Register the server with an absolute Homebrew path so desktop apps and IDE extensions do not depend on their inherited shell PATH.
Codex:
Claude Code:
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.6 is the current release. It adds typed actionable diagnostics, fixes Apple keyword bulk creation with zero-based integer correlation IDs and one aggregate cross-group receipt, and tightens read/query contracts without removing legacy id, filters, or top-level bulk adGroupId inputs. See the v0.3.6 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
| 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, 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:
- 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.6 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.
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.
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Apple Ads MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/apple-ads-mcp)HTML Embed
<a href="https://allmcps.com/mcp/apple-ads-mcp"><img src="https://allmcps.com/api/badge/apple-ads-mcp?style=directory" alt="Apple Ads MCP on AllMCPs" /></a>