Apple Ads MCP Server (read + write)

An MCP server for Apple Ads, built on the Apple Ads Platform API v1. Use it from Claude, ChatGPT, Cursor, Codex or any MCP client to report on App Store and Apple Maps campaigns, find search terms, keyword ideas and impression share, and change budgets, bids, keywords and ads.

Maintained by AI Shopping Feeds. It offers:

• nearly every Platform API v1 endpoint: campaigns, ad groups, keywords and negative keywords, ads and creatives, reports, impression share, search term popularity, recommendations, budget orders, Apple Maps and change history

• spend safety: dry-run, confirm words for deletes and bulk changes, a limit on budget and bid rises, paused new campaigns and an audit log

• every other endpoint through a generic apple_ads_request tool

• the current API: Apple switches off the older Campaign Management API v5 on 26 January 2027

Not affiliated with or endorsed by Apple.

Part of the AI Shopping Feeds MCP family: Google Ads · Google Merchant Centre · Google Analytics · YouTube Studio · Amazon Ads · Apple Ads · Microsoft Ads · TikTok Ads · Pinterest Ads · Snapchat Ads · OpenAI Ads · AppLovin.

Let your agent set it up

Paste this into Claude Code, Codex, Cursor or any agent that can read web pages and edit files:

Set up the Apple Ads MCP server for me by following https://raw.githubusercontent.com/AI-Shopping-Feeds/apple-ads-mcp/main/skills/apple-ads-mcp/SKILL.md

The agent checks whether it's already connected, installs the runner if you agree, walks you through the Apple Ads API user, key pair and IDs, adds the server to your client's config without touching your other servers, and checks it works by calling apple_ads_health_check.

The same file is an Agent Skill, so your agent can keep it as a guide to using the tools well. For Claude Code, copy the folder into your skills:

git clone --depth 1 https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git /tmp/apple-ads-mcp
cp -r /tmp/apple-ads-mcp/skills/apple-ads-mcp ~/.claude/skills/

Other agents that support skills load the same skills/apple-ads-mcp folder from their own skills directory.

Related MCP server: Apple Ads MCP

What it can do

89 tools, all prefixed apple_ads_. The full list is in docs/tools.md.

Read

Write

Safety

• Dry-run (APPLE_ADS_DRY_RUN=true or apple_ads_set_dry_run) previews and logs writes without sending them. Reads and reports still work.

• Deletes need confirm='DELETE'. Bulk changes, applying recommendations, budget orders and raw writes need confirm='APPLY'.

• Budget and bid rises above APPLE_ADS_MAX_INCREASE_PCT (default 20%) need confirm='APPLY', and the refusal shows the change, e.g. dailyBudget: 10.00 -> 15.00 (+50%). New campaigns start paused.

• Every write and dry-run is recorded in an append-only audit log (~/.apple-ads-mcp/logs/audit.jsonl) with a before snapshot. Entries older than APPLE_ADS_AUDIT_RETENTION_DAYS (default 30) are deleted at startup, and apple-ads-mcp purge deletes the log.

• APPLE_ADS_READ_ONLY=true hides every tool that can change the account; APPLE_ADS_TOOL_GROUPS exposes only the groups you need. Every tool carries a title and MCP read-only/destructive hints.

• The HTTP transports have no sign-in, so the server refuses to listen on anything but localhost unless you set APPLE_ADS_ALLOW_REMOTE=true.

• Report data stays in memory and is never written to disk. How the server fits Apple's terms: docs/terms-and-data.md.

Supported clients

Setup

1. Install uv

The server runs with uvx from uv (brew install uv on macOS) and needs Python 3.11 or later. It installs straight from this repository:

uvx --from git+https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git apple-ads-mcp

Pin a release by adding @vX.Y.Z to the URL.

2. Get credentials

1. API user: in Apple Ads, an account administrator invites a user under Account Settings > User Management with the API Account Read Only or API Account Manager (read and write) role.

2. Key pair: make one on your computer. The private key stays in ~/.apple-ads-mcp/secrets/; the command prints the public key:

   uvx --from git+https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git apple-ads-mcp keygen

3. Upload and copy your IDs: signed in as the API user, paste the public key into Account Settings > API and copy the clientId, teamId and keyId Apple shows.

Step by step, including how to find your ad account ID and the rules for working on clients' accounts: docs/setup-apple-ads-api.md.

3. Add it to your client

Replace the placeholders. Keep your other servers in each file. Start with APPLE_ADS_DRY_RUN=true so nothing changes until you're happy.

Claude Code

claude mcp add --scope user apple-ads \
  --env APPLE_ADS_CLIENT_ID=SEARCHADS.your-client-id \
  --env APPLE_ADS_TEAM_ID=SEARCHADS.your-team-id \
  --env APPLE_ADS_KEY_ID=your-key-id \
  --env APPLE_ADS_PRIVATE_KEY_PATH=/abs/path/private-key.pem \
  --env APPLE_ADS_DRY_RUN=true \
  -- uvx --from git+https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git apple-ads-mcp

Claude Desktop, Cursor, Gemini CLI, Windsurf (and VS Code under servers)

{
  "mcpServers": {
    "apple-ads": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git", "apple-ads-mcp"],
      "env": {
        "APPLE_ADS_CLIENT_ID": "SEARCHADS.your-client-id",
        "APPLE_ADS_TEAM_ID": "SEARCHADS.your-team-id",
        "APPLE_ADS_KEY_ID": "your-key-id",
        "APPLE_ADS_PRIVATE_KEY_PATH": "/abs/path/private-key.pem",
        "APPLE_ADS_DRY_RUN": "true"
      }
    }
  }
}

Desktop apps often can't find uvx on the PATH; if the server doesn't start, use the full path from which uvx as the command.

Codex (~/.codex/config.toml)

[mcp_servers.apple-ads]
command = "uvx"
args = ["--from", "git+https://github.com/AI-Shopping-Feeds/apple-ads-mcp.git", "apple-ads-mcp"]
env = { APPLE_ADS_CLIENT_ID = "SEARCHADS.your-client-id", APPLE_ADS_TEAM_ID = "SEARCHADS.your-team-id", APPLE_ADS_KEY_ID = "your-key-id", APPLE_ADS_PRIVATE_KEY_PATH = "/abs/path/private-key.pem", APPLE_ADS_DRY_RUN = "true" }

4. Check it works

Restart or reload the client, then ask it to "run the Apple Ads health check". It should call apple_ads_health_check and list the ad accounts your API user can see. Add the one you want as APPLE_ADS_AD_ACCOUNT_ID, and set APPLE_ADS_DRY_RUN=false when you're ready to make real changes.

Configuration

Settings can also go in ~/.apple-ads-mcp/.env, ./.env or a file passed with --env. See docs/mcp-client-config.md for the order, file locations and the command line (run, keygen, purge, describe, version).

Example prompts

How did my App Store campaigns do over the last 7 days? Which one has the worst cost per install?

Show last month's search terms for my US campaign and suggest negative keywords for the ones with spend and no installs.

Raise the daily budget of my UK campaign to £30. Use dry-run first and show me the change.

Which keywords in my main campaign have impression share under 30%?

More docs

• All tools

• Apple Ads API setup: API user, key pair, IDs, ad account and third-party rules

• MCP client configuration and every environment variable

• Terms and data handling

• Agent skill: setup and usage guide for agents

• Changelog and security policy

Contributing and licence

Issues and pull requests are welcome on this repository. See CONTRIBUTING.md.

Licensed under the MIT License.

Try out AI Shopping Feeds, our shopping feed management tool (including Google Shopping feeds).