apple-asc-mcp

A Model Context Protocol server that lets Claude Code — or any MCP client (Codex, Cursor, Windsurf, …) — drive an App Store release end-to-end:

xcodebuild → archive → export → upload → metadata → screenshots → submit for review

Claude does the work; you review the result in App Store Connect and tap Submit for Review.

Status: 0.2.0 (pre-1.0). API coverage is current as of Apple's OpenAPI v4.3 + WWDC 2025, and every tool's request shape has been cross-checked against Apple's published OpenAPI spec. The core release/monetization paths are live-validated against a real App Store Connect app — auth, metadata, screenshot upload, app-pricing discovery, the full in-app-purchase and subscription flows (create → localize → price → availability), age rating, content rights, users, and the delete tools all work against real Apple traffic. The remaining domains (webhooks, Xcode Cloud, reporting, Game Center, alternative distribution, in-app events, custom product pages, A/B experiments) are spec-confirmed but not yet exercised live — their shapes are correct per the spec but unproven against Apple's API. They carry [VERIFY] notes where a detail is still inferred. (App Privacy "nutrition label" tools were removed — that data isn't in the public App Store Connect API.) This is a 0.x release: expect shapes to move as tools meet live traffic, and pin your version. See Known limitations.

---

Table of contents

• What it does
• Quick start
• Apple setup walkthrough
• Configuration
• Wire into Claude Code
• Use with any MCP client
• End-to-end release flow
• Tool reference
• Troubleshooting
• Security & secret handling
• Comparison with fastlane / Transporter
• Known limitations
• Development
• License

---

What it does

158 MCP tools split across:

• Discovery (11) — asc_whoami, list/get apps, builds, versions, localizations, categories, territories, plus asc_release_status: a one-shot snapshot that tells Claude what's blocking submission.
• Build & upload (5) — xc_archive, xc_export_ipa, asc_validate_ipa, asc_upload_ipa (defaults to the new REST /v1/buildUploads flow from WWDC 2025; falls back to xcrun altool on demand), asc_wait_for_build_processing.
• Versioning & metadata (10) — create/update versions, attach builds, upsert per-locale description/keywords/promo text/what's new, set categories, set App Review demo credentials, and control the 7-day phased release (asc_set_phased_release).
• App pricing (3) — list price points, read the price schedule, set the app's price (free or paid; base territory + auto-equalize).
• Compliance declarations (3) — set the content-rights declaration, read/set the age-rating questionnaire.
• Submission gates (5) — set app territory availability (where it's sold) and manage export-compliance encryption declarations (list/create/assign-to-build).
• Screenshots & previews (7) — idempotent set-find-or-create, full reservation → multipart PUT → MD5 commit. Same code path covers iPhone/iPad/Watch/TV/Vision Pro/Mac and iMessage variants.
• Review submission (4) — modern reviewSubmissions flow.
• Customer reviews (4) — list/read App Store reviews and post/edit/delete the developer response.
• TestFlight (4) — list beta groups, set "What to test", distribute, submit for beta review.
• In-App Purchases (10) — create products, upsert per-locale name/description, price (base territory + auto-equalize), set availability, attach a review screenshot, submit, and delete. Consumable / Non-Consumable / Non-Renewing Subscription.
• Subscriptions (14) — subscription groups + group localizations, create auto-renewable subscriptions, per-locale name/description, pricing (base + auto-equalize), availability, introductory offers (free trial / pay-as-you-go / pay-up-front), review screenshot, group-level submission, and delete (subscription + empty group).
• Subscription promotional offers (4) — create/list/delete promotional offers (discounts for existing/lapsed subscribers) and add per-territory offer prices.
• Subscription offer codes & win-back (7) — offer codes (NEW/EXISTING/EXPIRED eligibility) with custom or one-time-use redeemable codes, and win-back offers (create/list/delete) for lapsed subscribers.
• Provisioning (13) — bundle IDs + capabilities, signing certificates, test devices, and provisioning profiles (code-signing automation, same auth as the rest).
• Webhooks (6) — create/list/update/delete app-event webhooks, ping, list deliveries.
• Users & access (6) — list/get/update team members, list/invite/cancel invitations (Admin key required).
• Xcode Cloud (6) — list products/workflows, get/start/list build runs (CI/CD).
• Reporting (4) — download Sales & Finance reports (gzipped TSV, parsed) and request App Store analytics reports.
• Game Center (7) — per-app detail, achievements + leaderboards with per-locale text.
• Alternative distribution (5) — EU-DMA distribution keys, packages, and marketplace domains.
• In-App Events (7) — create/list/update/delete time-boxed product-page events, per-locale text, and event card / details-page art (image + video clip). Schedule per territory; submit via asc_submit_for_review.
• Custom Product Pages (5) — create/list/get/delete per-audience variant pages with their own promo text and (reusing the screenshot/preview tools) their own visuals.
• Product Page Optimization (8) — A/B experiments: create/list/get/update (start/stop) experiments, add treatments (alternate icon + visuals), per-locale treatment localizations, and delete. Treatment visuals reuse the screenshot/preview tools.

See the tool reference for the full table.

Quick start

Prerequisites

• Node 20+. macOS 13+ with Xcode is only needed for the build/archive/validate tools (xc_archive, xc_export_ipa, asc_validate_ipa) and the altool upload fallback — everything else runs cross-platform.
• An App Store Connect API key (.p8 + Key ID + Issuer ID). If you don't have one yet, get it first via the Apple setup walkthrough, then come back to Step 2.

Step 1 — Install

npm install -g apple-asc-mcp

Or skip the install and run it on demand with npx:

npx apple-asc-mcp --diagnose

Step 2 — Set your credentials

If you haven't created an API key yet, follow the Apple setup walkthrough to generate it and place the .p8. Then export the three credentials in your current shell:

export APP_STORE_CONNECT_KEY_ID=ABCDEFGHIJ
export APP_STORE_CONNECT_ISSUER_ID=11111111-2222-3333-4444-555555555555
export APP_STORE_CONNECT_PRIVATE_KEY_PATH=~/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8

These last only for the current terminal. To make them permanent, append the three lines to your shell's startup file, then reload it:

# zsh (default on macOS)
cat >> ~/.zshrc <<'EOF'
export APP_STORE_CONNECT_KEY_ID=ABCDEFGHIJ
export APP_STORE_CONNECT_ISSUER_ID=11111111-2222-3333-4444-555555555555
export APP_STORE_CONNECT_PRIVATE_KEY_PATH=~/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8
EOF
source ~/.zshrc

# bash — same, but use ~/.bashrc (Linux) or ~/.bash_profile (macOS)

Step 3 — Verify your setup

apple-asc-mcp --diagnose

You should see all checks pass. If anything fails, the diagnose output names the file/env var to fix.

Step 4 — Wire into Claude Code

Claude Code launches the server in its own environment, which does not inherit the exports from Step 2. So pass the credentials to the registration directly:

claude mcp add --scope user apple-asc-mcp \
  -e APP_STORE_CONNECT_KEY_ID=ABCDEFGHIJ \
  -e APP_STORE_CONNECT_ISSUER_ID=11111111-2222-3333-4444-555555555555 \
  -- apple-asc-mcp

--scope user registers the server globally, for every project. Without it, claude mcp add defaults to local scope and the server only shows up in the directory you ran the command from.

The .p8 is found automatically when it lives at ~/.appstoreconnect/private_keys/AuthKey_<KEYID>.p8 (see Place the .p8). If you keep it somewhere else, add -e APP_STORE_CONNECT_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_ABCDEFGHIJ.p8.

(The Step 2 exports still matter — they're what let apple-asc-mcp --diagnose find your credentials from the terminal. The -e flags are the separate copy Claude Code's server process needs.)

Using a different MCP client (Codex, Cursor, Windsurf, …)? See Use with any MCP client — those clients pass the same three credentials in their own config's env block.

That's it. In Claude Code:

> Use asc_release_status for bundleId com.example.myapp to see what's blocking submission.
> Now create version 1.4.0 attached to the latest valid build.
> Set the en-US "What's New": "• Faster sync\n• HealthKit integration\n• Bug fixes"
> Submit for review.

Apple setup walkthrough

Create an App Store Connect API key

1. Sign in to App Store Connect with an Account Holder or Admin role.
2. Go to Users and Access → Integrations → App Store Connect API → Team Keys.
3. Click (+). Pick a name (e.g. "MCP release automation") and a role. Recommended: App Manager — it can manage versions, metadata, submissions, and TestFlight, but cannot edit users or pricing. For pricing/IAP automation, you'll need Admin or Finance.
4. Click Generate. Apple will show a Download API Key link once. Click it. The file AuthKey_<KEYID>.p8 is now in your Downloads folder. You cannot re-download it. If you lose it, you have to revoke the key and create a new one.
5. Note the Issuer ID (UUID at the top of the Integrations page) and the Key ID (10 characters next to your new key).

Place the .p8

The recommended location, which both altool and this MCP look in by default:

mkdir -p ~/.appstoreconnect/private_keys
mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/private_keys/
chmod 600 ~/.appstoreconnect/private_keys/*.p8

Verify

apple-asc-mcp --diagnose

You should see all checks pass. If anything fails, the diagnose output names the file/env var to fix.

Configuration

| Variable | Required | Notes | |---|---|---| | APP_STORE_CONNECT_KEY_ID | yes | 10-character Key ID shown next to the key in App Store Connect | | APP_STORE_CONNECT_ISSUER_ID | yes | UUID at the top of the Integrations page | | APP_STORE_CONNECT_PRIVATE_KEY_PATH | one of these | Path to the AuthKey_<KEYID>.p8 file | | APP_STORE_CONNECT_PRIVATE_KEY | | PEM contents inline (alternative to the path) | | APP_STORE_CONNECT_PREFER_REST_UPLOAD | no | true (default) uses /v1/buildUploads; false falls back to altool |

If neither path nor inline PEM is set, the server looks in altool's canonical locations:

~/.appstoreconnect/private_keys/AuthKey_<KEYID>.p8
~/.private_keys/AuthKey_<KEYID>.p8
./private_keys/AuthKey_<KEYID>.p8
./AuthKey_<KEYID>.p8

Wire into Claude Code

Pass the crede