Apple Ads MCP server

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 serverinfo, then run accounthealth 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.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.

Shortened. The full README is on GitHub.