Skip to main content
Glama

Apple Ads MCP

CI Release Go License

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 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.”

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

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.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_CONVERSIONS changes 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 requires LOC.

  • Default Product Page ad and creative deletion is confirmed as not_eligible because 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

.tar.gz

Linux container only

Linux arm64 / amd64

Yes

.tar.gz

Yes

Windows arm64 / amd64

No

.zip

Linux container only

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-ads entry, 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:

  1. Call optimization_baseline and optimization_plan in a read-only server.

  2. Review Apple recommendations separately from calculated actions.

  3. Start an authorized write session and call optimization_plan_preview.

  4. Inspect OperationImpact, apply the same receipt once, then call operations_verify.

  5. 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 PAUSED fixtures, 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 8601 startTime in 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 returns not_eligible during 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_suggestions and category_suggestions may return Apple HTTP 500 for a SUGGESTION query even when keyword_suggestions and target_cpa_suggestions work for the same owned app.

  • impression_share may return Apple HTTP 400 on a cold or fully paused account. An owner-controlled acceptance account supplied no code or diagnostic details; public reproductions have also reported code INVALID_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.py

See CONTRIBUTING.md, SECURITY.md, and the roadmap.

License

MIT

Available Tools

110 tools
account_healthC
Read-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_getB
Read-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_listB
Read-onlyIdempotent

Discover Apple Ads account ACLs available to a profile.

Inputs: profile (required). Returns: data, error, summary, rateLimit, +1 more

ad_create_previewC
Read-onlyIdempotent

Preview creation of one ad.

Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_delete_previewA
Read-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_getA
Read-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_previewB
Read-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_previewA
Read-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_previewC
Read-onlyIdempotent

Preview creation of one ad group.

Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_group_delete_previewA
Read-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_getB
Read-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_previewC
Read-onlyIdempotent

Preview pausing one ad group.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_group_reportC
Read-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_previewB
Read-onlyIdempotent

Preview resuming one ad group.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_group_schedule_previewB
Read-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_previewA
Read-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_queryC
Read-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_previewC
Read-onlyIdempotent

Preview App Store-only ad-group targeting.

Inputs: profile (required), adGroupId (required), targeting (required), adAccountId (required). Returns: error, preview, summary

ad_group_update_previewC
Read-onlyIdempotent

Preview an ad-group update.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_pause_previewC
Read-onlyIdempotent

Preview pausing one ad.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

ad_reportC
Read-onlyIdempotent

Read bounded ad performance rows.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

ad_resume_previewB
Read-onlyIdempotent

Preview resuming one ad.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

ads_queryC
Read-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_previewC
Read-onlyIdempotent

Preview an ad update.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

advertiser_resources_listB
Read-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_detailsA
Read-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_opportunitiesC
Read-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_getB
Read-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_queryB
Read-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_eligibilityC
Read-onlyIdempotent

Check App Store advertising eligibility.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

apps_getB
Read-onlyIdempotent

Read an App Store app by Adam ID.

Inputs: adamId (required), profile (required), adAccountId (required). Returns: data, error, summary, rateLimit, +1 more

auth_checkB
Read-onlyIdempotent

Validate OAuth credentials and return the caller identity.

Inputs: profile (required). Returns: data, error, summary, rateLimit, +1 more

campaign_auditB
Read-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_previewC
Read-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_previewB
Read-onlyIdempotent

Preview replacing campaign country targeting.

Inputs: profile (required), countries (required), campaignId (required), adAccountId (required). Returns: error, preview, summary

campaign_create_previewB
Read-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_previewB
Read-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_previewA
Read-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_getA
Read-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_inventoryC
Read-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_previewB
Read-onlyIdempotent

Preview pausing one campaign.

Inputs: profile (required), campaignId (required), adAccountId (required). Returns: error, preview, summary

campaign_reportC
Read-onlyIdempotent

Read bounded campaign performance rows.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

campaign_resume_previewC
Read-onlyIdempotent

Preview resuming one campaign.

Inputs: profile (required), campaignId (required), adAccountId (required). Returns: error, preview, summary

campaign_schedule_previewC
Read-onlyIdempotent

Preview a campaign start and end schedule update.

Inputs: id (required), profile (required), adAccountId (required), endTime, +1 more. Returns: error, preview, summary

campaign_shared_budget_assign_previewC
Read-onlyIdempotent

Preview assigning one LOC shared budget to one campaign.

Inputs: profile (required), campaignId (required), adAccountId (required), sharedBudgetId (required). Returns: error, preview, summary

campaign_shared_budget_unassign_previewB
Read-onlyIdempotent

Preview removing one shared-budget assignment from one campaign.

Inputs: profile (required), campaignId (required), adAccountId (required), sharedBudgetId (required). Returns: error, preview, summary

campaigns_queryC
Read-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_detailsC
Read-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_previewC
Read-onlyIdempotent

Preview a campaign update after reading current state.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

category_suggestionsC
Read-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_historyB
Read-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_detailB
Read-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_previewC
Read-onlyIdempotent

Preview creation of one creative.

Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

creative_delete_previewA
Read-onlyDestructiveIdempotent

Preview irreversible deletion of one unreferenced creative.

Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary

creative_getB
Read-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_queryB
Read-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_previewC
Read-onlyIdempotent

Preview a creative update.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

daily_budget_recommendation_apply_previewC
Read-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_previewC
Read-onlyIdempotent

Preview dismissing one daily-budget recommendation.

Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary

daily_budget_recommendationsB
Read-onlyIdempotent

Read daily-budget recommendations without applying them.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

impression_shareB
Read-onlyIdempotent

Read app impression-share insights through a typed UTC request.

Inputs: end (required), start (required), adamId (required), profile (required), +5 more. Returns: data, error, summary, rateLimit, +1 more

keyword_bid_previewB
Read-onlyIdempotent

Preview a targeting keyword bid update.

Inputs: bid (required), profile (required), keywordId (required), adAccountId (required), +2 more. Returns: error, preview, summary

keyword_create_previewC
Read-onlyIdempotent

Preview creation of one targeting keyword.

Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

keyword_delete_previewB
Read-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_getA
Read-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_previewB
Read-onlyIdempotent

Preview pausing one targeting keyword.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

keyword_reportB
Read-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_previewB
Read-onlyIdempotent

Preview resuming one targeting keyword.

Inputs: id (required), profile (required), adAccountId (required). Returns: error, preview, summary

keywords_bulk_create_previewA
Read-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_previewA
Read-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_queryB
Read-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_suggestionsC
Read-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_previewC
Read-onlyIdempotent

Preview a targeting keyword update.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

negative_keyword_create_previewC
Read-onlyIdempotent

Preview creation of one negative keyword.

Inputs: payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

negative_keyword_delete_previewA
Read-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_getA
Read-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_previewB
Read-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_previewB
Read-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_queryA
Read-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_previewB
Read-onlyIdempotent

Preview a negative keyword update.

Inputs: id (required), payload (required), profile (required), adAccountId (required). Returns: error, preview, summary

operations_applyA
Destructive

Apply exactly one non-expired, drift-free preview receipt.

Inputs: receipt (required). Returns: used, error, preview, receipt, +2 more

operations_inspectA
Read-onlyIdempotent

Inspect receipt binding, expiry, and use state without applying it.

Inputs: receipt (required). Returns: used, error, preview, receipt, +2 more

operations_verifyA
Read-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_baselineB
Read-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_historyC
Read-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_planC
Read-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_previewC
Read-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_listA
Read-onlyIdempotent

List named local optimization policies without credentials or account data.

Returns: data, error, summary, rateLimit, +1 more

optimization_policy_getA
Read-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_getC
Read-onlyIdempotent

Read one Apple Ads organization.

Inputs: orgId (required), profile (required). Returns: data, error, summary, rateLimit, +1 more

phrase_suggestionsC
Read-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_getB
Read-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_localesB
Read-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_queryB
Read-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_listA
Read-onlyIdempotent

List configured profile names without exposing credentials.

Returns: data, error, summary, rateLimit, +1 more

search_term_popularityC
Read-onlyIdempotent

Read search-term popularity insights.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

search_term_reportC
Read-onlyIdempotent

Read bounded search-term performance rows.

Inputs: profile (required), adAccountId (required), fields, filters, +5 more. Returns: data, error, summary, rateLimit, +1 more

server_infoA
Read-onlyIdempotent

Show server version, safety mode, API family, and response limits.

Returns: data, error, summary, rateLimit, +1 more

shared_budget_create_previewB
Read-onlyIdempotent

Preview LOC shared-budget creation using a private local billing profile.

Inputs: name (required), value (required), profile (required), startTime (required), +3 more. Returns: error, preview, summary

shared_budget_delete_previewB
Read-onlyDestructiveIdempotent

Preview irreversible deletion of one unassigned LOC shared budget.

Inputs: id (required), profile (required), adAccountId (required), expectedText (required). Returns: error, preview, summary

shared_budget_getA
Read-onlyIdempotent

Read one shared budget by ID for current-state verification.

Inputs: profile (required), adAccountId (required), id, sharedBudgetId. Returns: data, error, summary, rateLimit, +1 more

shared_budgets_queryB
Read-onlyIdempotent

Query bounded shared-budget metadata without invoice contacts.

Inputs: profile (required), adAccountId (required), id, fields, +7 more. Returns: data, error, summary, rateLimit, +1 more

shared_budget_update_previewC
Read-onlyIdempotent

Preview a typed LOC shared-budget update.

Inputs: profile (required), adAccountId (required), sharedBudgetId (required), name, +4 more. Returns: error, preview, summary

supported_app_languagesC
Read-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_previewB
Read-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_previewC
Read-onlyIdempotent

Preview dismissing one target-CPA recommendation.

Inputs: profile (required), adAccountId (required), promotedObjectId (required), recommendationId (required), +2 more. Returns: error, preview, summary

target_cpa_recommendationsA
Read-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_suggestionsC
Read-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

    C2.9/5.0

    Scored across 110 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Extends 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.
      13
      1
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      26
      374 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT