Apple Ads

io.github.Happygallo由 GitHub 帳號 Happygallo 發布v1.0.3更新於 Oct 24, 2026

Manage Apple Search Ads campaigns, keywords, budgets, and reports via API v5.

已驗證STDIO僅桌面資料與分析商業與電商

概覽

AI 產生的概覽

針對 Apple Search Ads API v5 的在地 MCP 伺服器，讓助理用自然語言管理廣告活動、關鍵字、預算與報表。

可以做什麼
  • 列出、建立、更新與刪除廣告活動和廣告群組，並取得活動與廣告群組報表
  • 新增、修改與移除指定關鍵字和排除關鍵字，調整出價，查看關鍵字報表
  • 檢視搜尋詞、廣告、創意和產品頁面，包括廣告被拒原因
  • 建立與管理預算訂單，分析預算使用情形，產生活動快照
  • 搜尋可投放的應用程式與地理位置，查看地區成效，建立曝光比重報表
  • 在多個組織之間切換，並讀取內建資源與流程提示
適用情境
適合正在投放 Apple Search Ads、想讓助理檢視成效、調整預算與出價、優化關鍵字與搜尋詞而不必登入網頁後台的人。已具備 Apple Search Ads 憑證的帳戶管理員或 API 使用者最適用。
執行需求
透過 npx（Node.js）以 stdio 在本機執行。需要一個 Apple Search Ads API 使用者，並設定四個環境變數：ASA_CLIENT_ID、ASA_TEAM_ID、ASA_KEY_ID 與 ASA_PRIVATE_KEY_PATH（或內嵌的 ASA_PRIVATE_KEY）。ASA_ORG_ID 為選用。需自行產生 PKCS#8 金鑰對並將公鑰上傳至 Apple。
安裝前請注意
需要私密金鑰檔案路徑或內嵌私密金鑰，該金鑰可存取廣告帳戶，務必妥善保管。伺服器可建立、更新與刪除廣告活動、廣告群組、關鍵字、廣告和預算訂單，並修改預算，助理的操作可能產生費用或刪除線上設定。若只需查看報表，建議使用唯讀 API 角色。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Apple Ads，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Apple Ads MCP

[npm version] [MCP compatible] [TypeScript] [License]

MCP server for the Apple Search Ads API v5.
Connect it to any MCP-compatible AI client and manage your campaigns, keywords, budgets, and reporting through natural language.

Quick Start • Tools • Resources • Prompts • Clients

Ask your AI things like:

"How did my campaigns perform last week?" "Pause the brand campaign and increase the budget on discovery to $500." "What search terms are triggering my ads? Add the best ones as exact-match keywords."

Supports 54 tools, 3 resources, and 6 prompts — campaigns, ad groups, keywords, creatives, budgets, search terms, geo targeting, impression share, and performance reports.

Features at a glance

FeatureDescription
Campaign managementCreate, update, pause, and delete campaigns and ad groups
Keyword optimizationAdd/remove targeting and negative keywords, update bids
Performance reportingCampaign, ad group, keyword, ad, and geo reports with date presets
Search term analysisSee actual search queries triggering your ads
Creative managementManage ads, creatives, and product pages
Budget controlCreate and manage budget orders, analyze utilization
Impression shareGenerate and retrieve impression share reports
Multi-org supportSwitch between organizations at runtime

Quick Start

  1. Get your Apple credentials (~10 min, one-time)
  2. Generate your key pair (2 commands)
  3. Add to your MCP client
  4. Start chatting

Setup

Step 1 — Invite an API user

Done by the account admin at searchads.apple.com.

  1. Go to Settings → User Management → Invite User
  2. Enter the email of the person who will use the API
  3. Set the role:
    • API Account Manager — full read/write access
    • API Account Read Only — view-only access
  4. Send the invitation

The API user must be a different Apple ID from the admin. If you're the admin, use a second Apple ID.

Step 2 — Accept and copy your credentials

Done by the invited user.

  1. Accept the email invitation and sign in to searchads.apple.com
  2. Go to Settings → API tab
  3. Copy and save these three values:
    • clientId — starts with SEARCHADS.
    • teamId — starts with SEARCHADS.
    • keyId — a UUID

Step 3 — Generate your key pair

Open Terminal and run:

bash
openssl ecparam -genkey -name prime256v1 -noout -out ~/apple-ads-key.pem && \openssl pkcs8 -topk8 -nocrypt -in ~/apple-ads-key.pem -out ~/apple-ads-key-pkcs8.pem

Then generate the public key:

bash
openssl ec -in ~/apple-ads-key-pkcs8.pem -pubout -out ~/apple-ads-key-public.pem

This creates:

  • ~/apple-ads-key-pkcs8.pem — private key (keep this safe, used in your config)
  • ~/apple-ads-key-public.pem — public key (upload to Apple next)

Step 4 — Upload public key to Apple

Print your public key:

bash
cat ~/apple-ads-key-public.pem

Copy the entire output (including the BEGIN / END lines), then:

  1. Go to Settings → API tab on searchads.apple.com
  2. Paste into the Public Key field
  3. Save

Step 5 — Add to your MCP client

Pick your client below and fill in your clientId, teamId, and keyId from Step 2, and the full path to your private key from Step 3.

Multiple orgs? Omit ASA_ORG_ID and use list_organizations / switch_organization at runtime. Or set it in env to pick a default.

Clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "apple-ads": {      "command": "npx",      "args": ["-y", "apple-ads-mcp"],      "env": {        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"      }    }  }}

Restart Claude Desktop after saving.

Claude Code
bash
claude mcp add apple-ads \  -e ASA_CLIENT_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \  -e ASA_TEAM_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \  -e ASA_KEY_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \  -e ASA_PRIVATE_KEY_PATH=/Users/yourname/apple-ads-key-pkcs8.pem \  -- npx -y apple-ads-mcp
Cursor

Add to .cursor/mcp.json:

json
{  "mcpServers": {    "apple-ads": {      "command": "npx",      "args": ["-y", "apple-ads-mcp"],      "env": {        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"      }    }  }}
VS Code

Add to your settings.json:

json
{  "mcp": {    "servers": {      "apple-ads": {        "command": "npx",        "args": ["-y", "apple-ads-mcp"],        "env": {          "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",          "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",          "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",          "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"        }      }    }  }}
Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

json
{  "mcpServers": {    "apple-ads": {      "command": "npx",      "args": ["-y", "apple-ads-mcp"],      "env": {        "ASA_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "ASA_PRIVATE_KEY_PATH": "/Users/yourname/apple-ads-key-pkcs8.pem"      }    }  }}
Other MCP clients

This server uses STDIO transport. Any MCP-compatible client can connect by running:

bash
npx -y apple-ads-mcp

Set these environment variables:

VariableDescription
ASA_CLIENT_IDYour client ID (starts with SEARCHADS.)
ASA_TEAM_IDYour team ID (starts with SEARCHADS.)
ASA_KEY_IDYour key ID (UUID)
ASA_PRIVATE_KEY_PATHAbsolute path to your PKCS#8 private key
ASA_ORG_ID(optional) Organization ID to use by default
Inline key (no file)

Replace ASA_PRIVATE_KEY_PATH with ASA_PRIVATE_KEY and paste the PEM content with \n for line breaks:

json
"ASA_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIGH...your-key...\n-----END PRIVATE KEY-----"

Tools

CategoryCountWhat you can do
Organizations3List and switch between organizations. Get user details.
Campaigns6List, create, update, delete campaigns. Pull performance reports.
Ad Groups6Manage ad groups within campaigns. Get ad group reports.
Keywords11Add/remove targeting and negative keywords. Update bids. Keyword reports.
Search Terms1See the actual queries people searched before tapping your ad.
Ads7List, create, update, delete ads. Get ad reports and rejection reasons.
Creatives5Manage creatives and product pages.
Budget Orders4Create, update, list, and get budget order details.
Apps & Geo5Search for eligible apps, check eligibility, find assets, search geolocations.
Geo Performance1Performance breakdown by country/region.
Impression Share3Create, list, and retrieve custom impression share reports.
Optimization2Campaign snapshots and budget utilization analysis.

All 54 tools

CategoryTools
Organizationslist_organizations, switch_organization, get_me_details
Campaignslist_campaigns, get_campaign_details, create_campaign, update_campaign, delete_campaign, get_campaign_report
Ad Groupslist_ad_groups, get_ad_group, create_ad_group, update_ad_group, delete_ad_group, get_adgroup_report
Keywordsget_keyword_report, list_targeting_keywords, get_targeting_keyword, add_targeting_keywords, update_targeting_keywords, delete_targeting_keywords, list_negative_keywords, get_negative_keyword, add_negative_keywords, update_negative_keywords, delete_negative_keywords
Search Termsget_search_term_report
Adslist_ads, get_ad, create_ad, update_ad, delete_ad, get_ad_report, find_ad_rejection_reasons
Creativeslist_creatives, get_creative, create_creative, list_product_pages, get_product_page_by_id
Budget Orderslist_budget_orders, get_budget_order, create_budget_order, update_budget_order
Apps & Geosearch_apps, get_app_details, get_app_eligibility, find_app_assets, search_geolocations
Geo Performanceget_geo_performance
Impression Sharecreate_impression_share_report, get_impression_share_report_by_id, list_impression_share_reports
Optimizationget_campaign_snapshot, get_budget_analysis

Resources

The server exposes 3 resources:

URIDescription
apple-ads://countriesSupported countries and regions for Apple Search Ads
apple-ads://device-sizesApp preview device sizes for creative assets
apple-ads://metrics-glossaryDefinitions, formulas, and benchmarks for all reporting metrics (CPA, CPT, TTR, etc.)

Prompts

6 built-in workflow prompts to guide common tasks:

PromptDescription
campaign_health_checkComprehensive campaign analysis — reviews spend, conversions, CPA trends, and flags issues
keyword_optimizationKeyword and search term optimization workflow — finds wasted spend and new opportunities
new_campaign_setupGuided new campaign creation — walks through app selection, structure, keywords, and budgets
budget_reallocationCross-campaign budget analysis — identifies over/under-spending and proposes budget shifts
creative_reviewCreative A/B review — compares ad performance, flags rejections, recommends winners
geo_expansionGeographic expansion analysis — ranks current markets and identifies new ones to enter
Troubleshooting

"pkcs8 must be PKCS#8 formatted string" Your key is in the wrong format. Re-run the openssl pkcs8 command from Step 3.

"No organization selected" Use list_organizations then switch_organization, or add ASA_ORG_ID to your config.

"Token request failed (401)" Verify your clientId, teamId, and keyId match Apple's API tab. Check that you uploaded your public key.

"Failed to read private key" Use an absolute path (e.g. /Users/yourname/...), not ~/....

Server disconnects immediately A required credential is missing. You need all four: ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, and ASA_PRIVATE_KEY_PATH.

Development
bash
git clone https://github.com/javiergalloroca/AppleAdsMCP.gitcd AppleAdsMCPnpm installnpm run buildnpm start

For hot reload: npm run dev

See CONTRIBUTING.md for contribution guidelines.

License

MIT

來源：README.md，提交 7f73700

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v1.0.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分