Apple Ads MCP
Provides tools for interacting with Apple Ads Platform API, including app discovery, keyword suggestions, advertising insights, reporting, campaign audits, and receipt-gated campaign management for Apple Search Ads.
Provides tools for looking up App Store apps, checking eligibility, and querying App Store product pages and product-page locales to support advertising research and campaign preparation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apple Ads MCP Audit my ad account health and recent change history."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 versionCreate 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-onlyRegister 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 listClaude Code:
claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-adsRestart 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.”
Related MCP server: pinterest-ads-mcp-server
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
Area | Main tools |
Access and readiness |
|
Apps and storefronts |
|
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 |
|
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
Platform | Homebrew | GitHub archive | OCI image |
macOS arm64 / amd64 | Yes |
| Linux container only |
Linux arm64 / amd64 | Yes |
| Yes |
Windows arm64 / amd64 | No |
| Linux container only |
Homebrew
The official tap installs a checksum-pinned release binary:
brew install zelentsov-dev/tap/apple-ads-mcpUpgrade later releases with:
brew update
brew upgrade apple-ads-mcpGitHub 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-mcpWindows 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.8The 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-mcpGo 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.pemUpload 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 initThe 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.pemValidate authentication and discover accessible ad accounts:
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-onlyConfiguration 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 --stdioFor 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 listCodex 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-adsClaude 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-writesThis 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-balancedPolicies 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-deletesThe 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/staticcheck@v0.8.1 -checks 'all,-ST1000,-ST1005' ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py
python3 scripts/audit_upstream.pySee CONTRIBUTING.md, SECURITY.md, and the roadmap.
License
Available Tools
110 toolsaccount_healthCRead-onlyIdempotent
Collect a read-only identity, access, and account baseline.
Inputs: profile (required), adAccountId (required), adamId. Returns: data, error, summary, rateLimit, +1 more
ad_account_getBRead-onlyIdempotent
Read sanitized account currency, timezone, payment model, features, and delegations.
Inputs: profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
ad_accounts_listBRead-onlyIdempotent
Discover Apple Ads account ACLs available to a profile.
Inputs: profile (required). Returns: data, error, summary, rateLimit, +1 more
ad_create_previewCRead-onlyIdempotent
Preview creation of one ad.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_delete_previewARead-onlyDestructiveIdempotent
Preview irreversible deletion of one ad under a paused campaign.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
ad_getARead-onlyIdempotent
Read one ad by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, adId. Returns: data, error, summary, rateLimit, +1 more
ad_group_bid_previewBRead-onlyIdempotent
Preview an ad-group default bid update with decimal amount and currency.
Inputs: amount (required), profile (required), currency (required), adGroupId (required), +1 more. Returns: error, preview, summary
ad_group_cpa_cap_previewARead-onlyIdempotent
Deprecated by Apple: preview a legacy ad-group CPA cap update; retained for compatibility without automatic strategy conversion.
Inputs: amount (required), profile (required), currency (required), adGroupId (required), +1 more. Returns: error, preview, summary
ad_group_create_previewCRead-onlyIdempotent
Preview creation of one ad group.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_group_delete_previewARead-onlyDestructiveIdempotent
Preview irreversible deletion of one ad group under a paused campaign.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
ad_group_getBRead-onlyIdempotent
Read one ad group by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, adGroupId. Returns: data, error, summary, rateLimit, +1 more
ad_group_pause_previewCRead-onlyIdempotent
Preview pausing one ad group.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_group_reportCRead-onlyIdempotent
Read bounded ad-group performance rows.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
ad_group_resume_previewBRead-onlyIdempotent
Preview resuming one ad group.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_group_schedule_previewBRead-onlyIdempotent
Preview an ad-group start and end schedule update.
Inputs: id (required), profile (required), adAccountId (required), endTime, +1 more. Returns: error, preview, summary
ad_group_search_match_previewARead-onlyIdempotent
Preview enabling or disabling Apple Search Match for a Search Results ad group.
Inputs: enabled (required), profile (required), adGroupId (required), adAccountId (required). Returns: error, preview, summary
ad_groups_queryCRead-onlyIdempotent
Query bounded ad groups with endpoint-specific filters.
Inputs: profile (required), adAccountId (required), id, fields, +8 more. Returns: data, error, summary, rateLimit, +1 more
ad_group_targeting_previewCRead-onlyIdempotent
Preview App Store-only ad-group targeting.
Inputs: profile (required), adGroupId (required), targeting (required), adAccountId (required). Returns: error, preview, summary
ad_group_update_previewCRead-onlyIdempotent
Preview an ad-group update.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_pause_previewCRead-onlyIdempotent
Preview pausing one ad.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
ad_reportCRead-onlyIdempotent
Read bounded ad performance rows.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
ad_resume_previewBRead-onlyIdempotent
Preview resuming one ad.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
ads_queryCRead-onlyIdempotent
Query bounded ads with endpoint-specific filters.
Inputs: profile (required), adAccountId (required), id, adId, +9 more. Returns: data, error, summary, rateLimit, +1 more
ad_update_previewCRead-onlyIdempotent
Preview an ad update.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
advertiser_resources_listBRead-onlyIdempotent
List App Store content-provider delegations available to a profile.
Inputs: profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
app_locale_detailsARead-onlyIdempotent
Query compact locale metadata, or full assets for one required languageCode.
Inputs: adamId (required), profile (required), adAccountId (required), fields, +8 more. Returns: data, error, summary, rateLimit, +1 more
app_opportunitiesCRead-onlyIdempotent
Collect independently classified eligibility and suggestion sections for an app.
Inputs: adamId (required), profile (required), adAccountId (required), countriesOrRegions (required), +1 more. Returns: data, error, summary, rateLimit, +1 more
app_rejection_reason_getBRead-onlyIdempotent
Read one App Store app rejection reason.
Inputs: profile (required), adAccountId (required), rejectionReasonId (required). Returns: data, error, summary, rateLimit, +1 more
app_rejection_reasons_queryBRead-onlyIdempotent
Query bounded App Store app rejection reasons.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
apps_eligibilityCRead-onlyIdempotent
Check App Store advertising eligibility.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
apps_getBRead-onlyIdempotent
Read an App Store app by Adam ID.
Inputs: adamId (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
apps_searchCRead-onlyIdempotent
Search apps; an empty result for a non-ASCII owned-app query gets one bounded exact-name fallback.
Inputs: profile (required), adAccountId (required), returnOwnedApps (required), cpids, +4 more. Returns: data, error, summary, rateLimit, +1 more
app_store_geo_searchCRead-onlyIdempotent
Search eligible App Store countries, administrative areas, and localities.
Inputs: profile (required), adAccountId (required), query, entity, +4 more. Returns: data, error, summary, rateLimit, +1 more
auth_checkBRead-onlyIdempotent
Validate OAuth credentials and return the caller identity.
Inputs: profile (required). Returns: data, error, summary, rateLimit, +1 more
campaign_auditBRead-onlyIdempotent
Collect campaign, ad-group, keyword, and search-term report baselines.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
campaign_bid_strategy_previewCRead-onlyIdempotent
Preview MANUAL_CPT or eligible App Store Search Results MAX_CONVERSIONS strategy.
Inputs: profile (required), strategy (required), campaignId (required), adAccountId (required). Returns: error, preview, summary
campaign_countries_previewBRead-onlyIdempotent
Preview replacing campaign country targeting.
Inputs: profile (required), countries (required), campaignId (required), adAccountId (required). Returns: error, preview, summary
campaign_create_previewBRead-onlyIdempotent
Preview creation of one campaign and return a ten-minute receipt.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
campaign_daily_budget_previewBRead-onlyIdempotent
Preview a campaign daily-budget update with typed money.
Inputs: amount (required), profile (required), campaignId (required), adAccountId (required). Returns: error, preview, summary
campaign_delete_previewARead-onlyDestructiveIdempotent
Preview irreversible deletion of one paused campaign and its cascade inventory.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
campaign_getARead-onlyIdempotent
Read one campaign by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, campaignId. Returns: data, error, summary, rateLimit, +1 more
campaign_inventoryCRead-onlyIdempotent
Read a campaign and bounded child inventory for safe auditing.
Inputs: profile (required), campaignId (required), adAccountId (required), pageSize. Returns: data, error, summary, rateLimit, +1 more
campaign_pause_previewBRead-onlyIdempotent
Preview pausing one campaign.
Inputs: profile (required), campaignId (required), adAccountId (required). Returns: error, preview, summary
campaign_reportCRead-onlyIdempotent
Read bounded campaign performance rows.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
campaign_resume_previewCRead-onlyIdempotent
Preview resuming one campaign.
Inputs: profile (required), campaignId (required), adAccountId (required). Returns: error, preview, summary
campaign_schedule_previewCRead-onlyIdempotent
Preview a campaign start and end schedule update.
Inputs: id (required), profile (required), adAccountId (required), endTime, +1 more. Returns: error, preview, summary
campaigns_queryCRead-onlyIdempotent
Query bounded campaigns with endpoint-specific filters.
Inputs: profile (required), adAccountId (required), id, fields, +7 more. Returns: data, error, summary, rateLimit, +1 more
campaign_status_reason_detailsCRead-onlyIdempotent
Read App Store campaign limited-status reason details.
Inputs: profile (required), campaignId (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
campaign_update_previewCRead-onlyIdempotent
Preview a campaign update after reading current state.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
category_suggestionsCRead-onlyIdempotent
Get category opportunities for an App Store app.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
change_historyBRead-onlyIdempotent
Read bounded Apple Ads change history for a required typed event window.
Inputs: end (required), start (required), profile (required), adAccountId (required), +19 more. Returns: data, error, summary, rateLimit, +1 more
change_history_detailBRead-onlyIdempotent
Read bounded field-level details for one change-history entry.
Inputs: profile (required), detailId (required), adAccountId (required), limit, +1 more. Returns: data, error, summary, rateLimit, +1 more
creative_create_previewCRead-onlyIdempotent
Preview creation of one creative.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
creative_delete_previewARead-onlyDestructiveIdempotent
Preview irreversible deletion of one unreferenced creative.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
creative_getBRead-onlyIdempotent
Read one creative by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, creativeId. Returns: data, error, summary, rateLimit, +1 more
creatives_queryBRead-onlyIdempotent
Query bounded App Store creatives with endpoint-specific filters.
Inputs: profile (required), adAccountId (required), id, fields, +7 more. Returns: data, error, summary, rateLimit, +1 more
creative_update_previewCRead-onlyIdempotent
Preview a creative update.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
daily_budget_recommendation_apply_previewCRead-onlyIdempotent
Preview applying one daily-budget recommendation under an explicit maximum.
Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary
daily_budget_recommendation_dismiss_previewCRead-onlyIdempotent
Preview dismissing one daily-budget recommendation.
Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary
daily_budget_recommendationsBRead-onlyIdempotent
Read daily-budget recommendations without applying them.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
keyword_bid_previewBRead-onlyIdempotent
Preview a targeting keyword bid update.
Inputs: bid (required), profile (required), keywordId (required), adAccountId (required), +2 more. Returns: error, preview, summary
keyword_create_previewCRead-onlyIdempotent
Preview creation of one targeting keyword.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
keyword_delete_previewBRead-onlyDestructiveIdempotent
Preview irreversible deletion of one keyword under a paused campaign.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
keyword_getARead-onlyIdempotent
Read one targeting keyword by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, keywordId. Returns: data, error, summary, rateLimit, +1 more
keyword_pause_previewBRead-onlyIdempotent
Preview pausing one targeting keyword.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
keyword_reportBRead-onlyIdempotent
Read bounded keyword performance rows, optionally including EMPTY_METRICS.
Inputs: profile (required), adAccountId (required), fields, filters, +6 more. Returns: data, error, summary, rateLimit, +1 more
keyword_resume_previewBRead-onlyIdempotent
Preview resuming one targeting keyword.
Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary
keywords_bulk_create_previewARead-onlyIdempotent
Preview up to 100 same- or cross-group keyword creates as one Apple bulk request and aggregate receipt.
Inputs: items (required), profile (required), adGroupId (required), adAccountId (required). Returns: error, preview, summary
keywords_bulk_update_previewARead-onlyIdempotent
Preview up to 100 targeting keyword updates as one drift-bound operation.
Inputs: items (required), profile (required), adGroupId (required), adAccountId (required). Returns: error, preview, summary
keywords_queryBRead-onlyIdempotent
Query bounded targeting-keyword inventory with a required typed scope.
Inputs: profile (required), adAccountId (required), id, fields, +9 more. Returns: data, error, summary, rateLimit, +1 more
keyword_suggestionsCRead-onlyIdempotent
Get keyword opportunities for an App Store app.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
keyword_update_previewCRead-onlyIdempotent
Preview a targeting keyword update.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
negative_keyword_create_previewCRead-onlyIdempotent
Preview creation of one negative keyword.
Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
negative_keyword_delete_previewARead-onlyDestructiveIdempotent
Preview irreversible deletion of one negative keyword under a paused campaign.
Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary
negative_keyword_getARead-onlyIdempotent
Read one negative keyword by ID for current-state verification.
Inputs: profile (required), adAccountId (required), id, negativeKeywordId. Returns: data, error, summary, rateLimit, +1 more
negative_keywords_bulk_create_previewBRead-onlyIdempotent
Preview up to 100 negative keyword creates in one scope.
Inputs: items (required), profile (required), adAccountId (required), adGroupId, +1 more. Returns: error, preview, summary
negative_keywords_bulk_update_previewBRead-onlyIdempotent
Preview up to 100 negative keyword updates in one scope.
Inputs: items (required), profile (required), adAccountId (required), adGroupId, +1 more. Returns: error, preview, summary
negative_keywords_queryARead-onlyIdempotent
Query bounded negative-keyword inventory with a valid campaign or ad-group scope.
Inputs: profile (required), adAccountId (required), id, fields, +9 more. Returns: data, error, summary, rateLimit, +1 more
negative_keyword_update_previewBRead-onlyIdempotent
Preview a negative keyword update.
Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary
operations_applyADestructive
Apply exactly one non-expired, drift-free preview receipt.
Inputs: receipt (required). Returns: used, error, preview, receipt, +2 more
operations_inspectARead-onlyIdempotent
Inspect receipt binding, expiry, and use state without applying it.
Inputs: receipt (required). Returns: used, error, preview, receipt, +2 more
operations_verifyARead-onlyIdempotent
Re-read receipt targets after an ambiguous write, including restart-safe optimization recovery, and return current state.
Inputs: receipt (required). Returns: used, error, preview, receipt, +2 more
optimization_baselineBRead-onlyIdempotent
Build a bounded 28-day Apple Ads performance baseline for a named policy.
Inputs: policy (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
optimization_historyCRead-onlyIdempotent
Read bounded local decisions and verification history for a named policy.
Inputs: policy (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
optimization_planCRead-onlyIdempotent
Build an on-demand bounded optimization plan without creating a receipt.
Inputs: policy (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
optimization_plan_previewCRead-onlyIdempotent
Build and bind one bounded active-policy optimization plan to a composite receipt.
Inputs: policy (required), profile (required), adAccountId (required). Returns: error, preview, summary
optimization_policies_listARead-onlyIdempotent
List named local optimization policies without credentials or account data.
Returns: data, error, summary, rateLimit, +1 more
optimization_policy_getARead-onlyIdempotent
Read one named optimization policy with resolved balanced thresholds.
Inputs: policy (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more
org_getCRead-onlyIdempotent
Read one Apple Ads organization.
Inputs: orgId (required), profile (required). Returns: data, error, summary, rateLimit, +1 more
phrase_suggestionsCRead-onlyIdempotent
Get phrase opportunities for an App Store app.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
product_page_getBRead-onlyIdempotent
Read a Default or Custom Product Page by ID.
Inputs: profile (required), adAccountId (required), productPageId (required). Returns: data, error, summary, rateLimit, +1 more
product_page_localesBRead-onlyIdempotent
Query bounded Product Page locale details.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
product_pages_queryBRead-onlyIdempotent
Query bounded Default and Custom Product Pages.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
profiles_listARead-onlyIdempotent
List configured profile names without exposing credentials.
Returns: data, error, summary, rateLimit, +1 more
search_term_popularityCRead-onlyIdempotent
Read search-term popularity insights.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
search_term_reportCRead-onlyIdempotent
Read bounded search-term performance rows.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
server_infoARead-onlyIdempotent
Show server version, safety mode, API family, and response limits.
Returns: data, error, summary, rateLimit, +1 more
supported_app_languagesCRead-onlyIdempotent
Query bounded App Store advertising language metadata.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
target_cpa_recommendation_apply_previewBRead-onlyIdempotent
Preview applying one target-CPA recommendation under an explicit maximum.
Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary
target_cpa_recommendation_dismiss_previewCRead-onlyIdempotent
Preview dismissing one target-CPA recommendation.
Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary
target_cpa_recommendationsARead-onlyIdempotent
Read target-CPA recommendations without applying them.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
target_cpa_suggestionsCRead-onlyIdempotent
Get target CPA suggestions.
Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 110 tools
With 110 tools, many near-identical variants exist across resources, such as pause/resume/update/delete previews for campaigns, ad groups, ads, keywords, and negatives. Audit, planning, query, and reporting tools like campaign_audit, optimization_plan, optimization_plan_preview, and account_health have boundaries that are only clear after reading long descriptions, creating real misselection risk.
Tool names are overwhelmingly snake_case and follow predictable resource_action or action_preview patterns. There are minor inconsistencies in singular/plural resource naming, e.g. campaign_get vs campaigns_query and app_get-style patterns vs apps_get/apps_search, plus a few noun-first names like account_health and server_info, but the convention remains readable.
A 110-tool surface is an extreme mismatch for a coherent MCP toolset and far exceeds the 3-15 range where tools can be reliably selected. Many operations are near-duplicate previews or resource-specific variants that could be consolidated through generic resource/action tools or namespacing.
The surface covers the Apple Ads domain broadly: campaigns, ad groups, ads, keywords, negative keywords, creatives, shared budgets, product pages, apps, geo/eligibility, reports, recommendations, change history, auth, and optimization workflows. Mutation paths are consistently modeled through preview receipts plus apply/verify, leaving few obvious dead ends.
Maintenance
Related MCP Connectors
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Apple Search Ads MCP: campaign analytics, bid management, and attribution tracking.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Hosted Meta ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Related MCP Servers
- AlicenseAqualityBmaintenanceExtends the official Google Ads MCP with a safe write layer for creating paused-by-default Search campaigns and an account auditor, all running locally with no hosted dependencies.131Apache 2.0
- AlicenseBqualityBmaintenanceEnables MCP clients to read and analyze Pinterest advertising data, with optional guarded write tools that preview changes before applying them, all while keeping your token on your own machine and protecting lead records.26374 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceGives MCP clients read-only access to every GET endpoint of Apple's Campaign Management v5 and Apple Ads Platform v1 APIs across multiple ad accounts, over stdio or Streamable HTTP. It exposes one tool per endpoint with per-account OAuth handling, pagination, and structured errors, while excluding all mutation and POST-only reporting endpoints.94 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables searching an offline catalog of Apple Ads Platform API documentation and issuing authenticated read and write calls to manage App Store and Apple Maps campaigns, reports, keywords, budgets, and recommendations. Read and write are split into separate tools, with read-only mode, pagination merging, and large-report file output.93 npmMIT