convez.ai
MCP ServerDevOps & InfraestruturaAvançado
warunacds

Apple App Store Connect MCP

warunacds/apple-asc-mcp

Automatize lançamentos iOS end-to-end via Claude com 158 ferramentas App Store Connect

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que permite ao Claude Code (ou qualquer cliente MCP) automatizar o ciclo completo de lançamento no App Store Connect: compilação, upload, metadados, screenshots e submissão para revisão. Integra-se nativamente com Xcode e a API oficial da Apple, eliminando a necessidade de ferramentas intermediárias como fastlane.

Instalação

$npx convez-ai warunacds/apple-asc-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automatizar build, upload e submissão de apps no App Store
  • Gerenciar metadados, screenshots e informações de localização via IA
  • Configurar preços, subscrições e compras in-app programaticamente
  • Streamline do fluxo de release integrado com Xcode Cloud

Veredito

Ferramenta especializada e bem-estruturada para quem precisa automatizar lançamentos iOS em larga escala. Status 0.2.0 com cobertura API completa e validação contra tráfego real da Apple; recomenda-se pinnar versão em produção.

README

A tradução para o português deste README ainda está na fila.

apple-asc-mcp

CI npm version License: MIT Node ≥20

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

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 apple-asc-mcp \
  -e APP_STORE_CONNECT_KEY_ID=ABCDEFGHIJ \
  -e APP_STORE_CONNECT_ISSUER_ID=11111111-2222-3333-4444-555555555555 \
  -e APP_STORE_CONNECT_PRIVATE_KEY_PATH=~/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8 \
  -- apple-asc-mcp

(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

VariableRequiredNotes
APP_STORE_CONNECT_KEY_IDyes10-character Key ID shown next to the key in App Store Connect
APP_STORE_CONNECT_ISSUER_IDyesUUID at the top of the Integrations page
APP_STORE_CONNECT_PRIVATE_KEY_PATHone of thesePath to the AuthKey_<KEYID>.p8 file
APP_STORE_CONNECT_PRIVATE_KEYPEM contents inline (alternative to the path)
APP_STORE_CONNECT_PREFER_REST_UPLOADnotrue (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 credentials to the registration — Claude Code launches the server in its own environment and won't pick up your shell exports:

claude mcp add apple-asc-mcp \
  -e APP_STORE_CONNECT_KEY_ID=ABCDEFGHIJ \
  -e APP_STORE_CONNECT_ISSUER_ID=11111111-2222-3333-4444-555555555555 \
  -e APP_STORE_CONNECT_PRIVATE_KEY_PATH=~/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8 \
  -- apple-asc-mcp

…or write the same thing to ~/.claude.json directly:

{
  "mcpServers": {
    "apple-asc-mcp": {
      "command": "apple-asc-mcp",
      "env": {
        "APP_STORE_CONNECT_KEY_ID": "ABCDEFGHIJ",
        "APP_STORE_CONNECT_ISSUER_ID": "11111111-2222-3333-4444-555555555555",
        "APP_STORE_CONNECT_PRIVATE_KEY_PATH": "/Users/me/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8"
      }
    }
  }
}

Verify it loaded with:

> Use asc_whoami to check the App Store Connect connection.

Use with any MCP client

This is a standard stdio MCP server — nothing about it is Claude-specific. Any MCP-capable client speaks to it the same way; only the registration differs. Point the client at the appstore-connect-mcp command (or npx -y appstore-connect-mcp) and pass the three credential env vars.

OpenAI Codex — add to ~/.codex/config.toml:

[mcp_servers.appstore-connect]
command = "npx"
args = ["-y", "appstore-connect-mcp"]
env = { APP_STORE_CONNECT_KEY_ID = "ABCDEFGHIJ", APP_STORE_CONNECT_ISSUER_ID = "11111111-2222-3333-4444-555555555555", APP_STORE_CONNECT_PRIVATE_KEY_PATH = "/Users/me/.appstoreconnect/private_keys/AuthKey_ABCDEFGHIJ.p8" }

(Recent Codex also has a codex mcp add helper — see codex mcp --help.)

Cursor / Windsurf / VS Code / Zed / Cline and most others use the same JSON shape as the ~/.claude.json block above — a mcpServers (or editor-specific) entry with command, args, and env. Drop the same three env vars in.

Heads-up on the tool count. This server exposes ~150 tools. Claude Code lazy-loads tool schemas, so the full surface costs almost nothing in context until a tool is used. Clients that don't lazy-load register every schema up front — that's token-heavy, and a few clients/models cap how many tools they'll accept. The server works regardless; if your client struggles with large tool sets, that's the cause. (The macOS/Xcode requirement for xc_archive / xc_export_ipa / asc_validate_ipa is an environment constraint, independent of the client.)

End-to-end release flow

The flow Claude follows when you say "ship 1.4.0 to the App Store":

  1. Snapshot. asc_release_status appId=… returns the editable version, latest VALID build, missing localizations, missing screenshots, and a blockers list. Always start here.
  2. Build & upload (if a fresh build is needed).
    • xc_archive { workspacePath, scheme, archivePath }
    • xc_export_ipa { archivePath, exportPath, exportOptions: { method: "app-store-connect", teamID, signingStyle, … } }
    • asc_validate_ipa { ipaPath, … } (cheap pre-flight; catches signing / entitlement / ITMS errors before upload)
    • asc_upload_ipa { ipaPath, bundleVersion, platform: "IOS" }
    • asc_wait_for_build_processing { appId, bundleVersion } polls until VALID
  3. Version.
    • asc_create_version { appId, versionString: "1.4.0", platform: "IOS", buildId }, or
    • asc_attach_build_to_version { versionId, buildId } if the version already exists.
  4. Localizations. For each locale, asc_set_version_localization with description, keywords, whatsNew, promotionalText, marketingUrl, supportUrl.
  5. App-level info. asc_get_editable_app_info → asc_set_app_categories → asc_set_app_info_localization (name, subtitle, privacy URL).
  6. Screenshots. Per (locale, displayType): asc_find_or_create_screenshot_set → loop asc_upload_screenshot for each PNG/JPG → optional asc_reorder_screenshots. Same shape for asc_upload_preview.
  7. Review details. asc_set_review_details with contact info and demo credentials (required if your app has a login).
  8. Submit. asc_submit_for_review { appId, versionId, platform } creates the reviewSubmission, adds the version as an item, and PATCHes submitted: true.
  9. Track. asc_get_review_submission { submissionId }. Use asc_release_to_store after Apple approves to push a PENDING_DEVELOPER_RELEASE build live.

For TestFlight: asc_set_beta_whats_new → asc_distribute_to_beta_groups (internal-only) or asc_submit_for_beta_review (external testers).

See examples/release.example.json for a sample metadata payload.

Tool reference

Discovery & status

ToolRequired inputsPurpose
asc_whoami—Verify auth works; lists 1 app to confirm
asc_list_apps—List visible apps; filter by bundleId or name
asc_get_appappId or bundleIdSingle app, with sideloaded versions/builds/appInfos
asc_list_buildsappIdBuilds; filter by processingState, version, expired
asc_get_buildbuildIdSingle build, with preReleaseVersion + appStoreVersion
asc_list_versionsappIdVersions for an app; filter by platform, appVersionState
asc_get_versionversionIdSingle version + build + localizations + review detail
asc_list_version_localizationsversionIdPer-locale marketing copy under a version
asc_list_categories—Discover category ids for asc_set_app_categories
asc_list_territories—Territory codes (USA, GBR, …) for the pricing/availability tools
asc_release_statusappId or bundleIdOne-shot "what's blocking submission" snapshot

Build, validate, upload (macOS for the first three)

ToolRequired inputsPurpose
xc_archivescheme, archivePath, one of workspacePath/projectPathxcodebuild ... archive
xc_export_ipaarchivePath, exportPath, one of exportOptionsPlist/exportOptionsxcodebuild -exportArchive (auto-generates plist if you pass exportOptions)
asc_validate_ipaipaPathPre-flight via xcrun altool --validate-app
asc_upload_ipaipaPath, bundleVersionREST /v1/buildUploads (default) or altool
asc_wait_for_build_processingappId, bundleVersionPolls until VALID/INVALID/timeout

Version & metadata

ToolRequired inputsPurpose
asc_create_versionappId, versionStringNew App Store Version; optionally attach a build
asc_update_versionversionIdEdit versionString/copyright/releaseType/etc.
asc_attach_build_to_versionversionId, buildIdSet or swap the binary on a version
asc_set_version_localizationversionId, localeUpsert description, keywords, whatsNew, etc.
asc_release_to_storeversionIdManually release a PENDING_DEVELOPER_RELEASE build
asc_set_phased_releaseversionIdEnable / pause / resume / complete the 7-day phased rollout
asc_get_editable_app_infoappIdFind the editable AppInfo (state=PREPARE_FOR_SUBMISSION)
asc_set_app_categoriesappInfoId, primaryCategoryIdSet primary/secondary categories
asc_set_app_info_localizationappInfoId, localeUpsert name, subtitle, privacy URL
asc_set_review_detailsversionIdContact info + demo credentials

App pricing

The app's own price (free or paid), distinct from in-app-purchase pricing. Apple uses fixed, server-defined price points per territory — you pick a tier, you don't type an amount. asc_set_app_price resolves a customerPrice like "4.99" to the matching point in the base territory (or free: true for the $0 tier); territories you don't list auto-equalize.

ToolRequired inputsPurpose
asc_list_app_price_pointsappIdValid price tiers for a territory
asc_get_app_price_scheduleappIdThe app's current price schedule
asc_set_app_priceappIdSet price (free, customerPrice, or pricePointId); auto-equalizes

Validation status. Like the rest of the server, these are not yet exercised against live Apple traffic; the price-schedule shape is inferred from research/api-reference.md §12. If a call 400s, attach the JSON:API error body to an issue.

Compliance declarations

Submission gates beyond metadata. (App-privacy "nutrition label" data usages are in the next section.)

ToolRequired inputsPurpose
asc_set_content_rightsappId, usesThirdPartyContentDeclare third-party content rights on the app
asc_get_age_ratingappIdRead the age-rating questionnaire
asc_set_age_ratingappIdSet questionnaire answers (resolves the editable AppInfo + declaration)

Validation status. [VERIFY] — and note Apple overhauled the age-rating questionnaire in 2024–25 (new bands/questions). asc_set_age_rating PATCHes only the fields you pass and takes an additionalDeclarations escape hatch for questions not in the typed list.

Submission gates

Final blockers beyond version metadata: where the app is sold, and export compliance.

ToolRequired inputsPurpose
asc_get_app_availabilityappIdTerritories the app is available in
asc_set_app_availabilityappIdSet territories (or availableInAllTerritories) + auto-add-new flag
asc_list_encryption_declarationsappIdExisting export-compliance declarations
asc_create_encryption_declarationappId, appDescription, containsProprietaryCryptography, containsThirdPartyCryptography, availableOnFrenchStoreExport-compliance declaration (HTTPS-only apps answer false to both crypto flags)
asc_assign_encryption_declarationbuildId, declarationIdAttach a declaration to a build

Validation status. Write shapes cross-checked against the App Store Connect OpenAPI spec: set_app_availability inlines territoryAvailabilities resources, and the encryption declaration is appDescription + two cryptography flags. Not yet exercised against live Apple traffic — if a call 400s, attach the JSON:API error body to an issue.

Screenshots & previews

ToolRequired inputsPurpose
asc_list_screenshot_setslocalizationIdList sets under a localization
asc_find_or_create_screenshot_setone of localizationId / customProductPageLocalizationId / experimentTreatmentLocalizationId, + displayTypeIdempotent set get/create (default page, Custom Product Page, or experiment treatment)
asc_upload_screenshotsetId, filePathReservation → multipart PUT → MD5 commit
asc_delete_screenshotscreenshotIdRemove one screenshot
asc_reorder_screenshotssetId, screenshotIds[]Change display order
asc_find_or_create_preview_setone of localizationId / customProductPageLocalizationId / experimentTreatmentLocalizationId, + previewTypeIdempotent video set get/create
asc_upload_previewsetId, filePathSame flow as screenshots, for video

Review submission

ToolRequired inputsPurpose
asc_submit_for_reviewappId, versionIdEnd-to-end: create submission → add item → PATCH submitted=true
asc_get_review_submissionsubmissionIdState + items
asc_list_review_submissionsappIdRecent submissions
asc_cancel_review_submissionsubmissionIdPull back if not yet picked up

Customer reviews

Read App Store customer reviews and manage the developer response. (Distinct from the review-submission flow above.) Reading needs no special role; posting responses may need a higher one.

ToolRequired inputsPurpose
asc_list_customer_reviewsappIdList reviews (filter territory/rating, sort by date/rating)
asc_get_customer_reviewreviewIdA single review + its response
asc_respond_to_reviewreviewId, responseBodyUpsert the developer response
asc_delete_review_responseresponseIdRemove a response

Validation status. [VERIFY] — the response relationship path (/v1/customerReviews/{id}/response) is inferred. If a call 400s, attach the JSON:API error body to an issue.

TestFlight

ToolRequired inputsPurpose
asc_list_beta_groupsappIdInternal + external groups
asc_set_beta_whats_newbuildId, locale, whatsNewPer-locale "What to Test"
asc_distribute_to_beta_groupsbuildId, groupIds[]Push a build to one or more groups
asc_submit_for_beta_reviewbuildIdRequired before external distribution

In-App Purchases

Covers Consumable, Non-Consumable, and Non-Renewing Subscription products. Auto-renewable subscriptions and offers are deliberately a later phase.

ToolRequired inputsPurpose
asc_list_in_app_purchasesappIdList IAPs; filter by inAppPurchaseType/state
asc_get_in_app_purchaseinAppPurchaseIdSingle IAP + localizations + price schedule + availability
asc_create_in_app_purchaseappId, name, productId, inAppPurchaseTypeCreate the product (productId is immutable)
asc_set_iap_localizationinAppPurchaseId, localeUpsert customer-facing name (≤30) + description (≤45)
asc_list_iap_price_pointsinAppPurchaseIdDiscover valid price tiers for a territory
asc_set_iap_priceinAppPurchaseIdBase territory + customerPrice/pricePointId; other territories auto-equalize
asc_set_iap_availabilityinAppPurchaseIdTerritory availability (codes or availableInAllTerritories)
asc_upload_iap_review_screenshotinAppPurchaseId, filePathReservation → PUT → MD5 commit (App Review screenshot)
asc_submit_iap_for_reviewinAppPurchaseIdStandalone IAP submission (or bundle via asc_submit_for_review)
asc_delete_in_app_purchaseinAppPurchaseIdPermanently delete an IAP (only while still editable)

Typical flow:

> Create a non-consumable IAP "Pro Upgrade" productId com.example.app.pro for appId 12345.
> Set its en-US name "Pro Upgrade" and description "Unlock every feature, forever."
> Price it at $4.99 (base territory USA) — other territories auto-equalize.
> Make it available in all territories, upload ~/screens/iap-review.png as the review screenshot, and submit it for review.

Pricing model. Apple uses fixed, server-defined price points per territory — you pick a tier, you don't type an amount. asc_set_iap_price resolves a customerPrice like "4.99" to the matching point in the base territory; pass an explicit pricePointId (from asc_list_iap_price_points) for precision. Territories you don't list are auto-derived from the base.

Validation status. Like the rest of the server, the IAP tools have not been exercised against live Apple traffic. Four spec details are marked [VERIFY] in src/tools/iap.ts (the inAppPurchaseV2 vs inAppPurchase relationship keys, the standalone inAppPurchaseSubmissions submit path, and price-schedule auto-equalization). If one 400s, attach the JSON:API error body to an issue.

Subscriptions

Auto-renewable subscriptions. A subscription lives inside a subscription group; a customer can hold only one active subscription per group, and groupLevel ranks the upgrade/downgrade tiers. Submission happens at the group level.

ToolRequired inputsPurpose
asc_list_subscription_groupsappIdGroups + their subscriptions
asc_create_subscription_groupappId, referenceNameCreate a group (internal name)
asc_set_subscription_group_localizationsubscriptionGroupId, localeUpsert customer-facing group name (+ optional customAppName)
asc_create_subscriptiongroupId, name, productId, subscriptionPeriodCreate an auto-renewable subscription in a group
asc_get_subscriptionsubscriptionIdSingle subscription + localizations/prices/availability/offers
asc_set_subscription_localizationsubscriptionId, localeUpsert customer-facing name (≤30) + description (≤45)
asc_list_subscription_price_pointssubscriptionIdDiscover valid price tiers for a territory
asc_set_subscription_pricesubscriptionIdBase territory + customerPrice/pricePointId; auto-equalizes
asc_set_subscription_availabilitysubscriptionIdTerritory availability
asc_set_subscription_intro_offersubscriptionId, offerMode, durationFree trial / pay-as-you-go / pay-up-front offer
asc_upload_subscription_review_screenshotsubscriptionId, filePathReservation → PUT → MD5 commit
asc_submit_subscription_for_reviewsubscriptionGroupIdSubmit the whole group for review
asc_delete_subscriptionsubscriptionIdPermanently delete a subscription (only while still editable)
asc_delete_subscription_groupsubscriptionGroupIdDelete an empty subscription group

Typical flow:

> Create a subscription group "Pro" for appId 12345 and set its en-US name "Pro".
> Add a monthly auto-renewable subscription "Pro Monthly" productId com.example.app.pro.monthly, groupLevel 1.
> Set its en-US name "Pro Monthly" and description "Everything in Pro, billed monthly."
> Price it at $9.99 (base USA), give it a 1-month free trial, make it available everywhere.
> Upload ~/screens/sub-review.png and submit the Pro group for review.

Validation status. Same [VERIFY] caveats apply (see src/tools/subscriptions.ts): the subscription/subscriptionGroup relationship keys, subscription-price auto-equalization (subscriptions have no price-schedule resource — prices are created per territory), the introductory-offer territory/price-point shape, and the group-level subscriptionGroupSubmissions submit path.

Subscription promotional offers

Discounts for existing or lapsed subscribers (distinct from introductory offers, which target new subscribers). Each offer has a developer-defined offerCode (referenced by StoreKit at purchase) and a discounted price per territory.

ToolRequired inputsPurpose
asc_list_promotional_offerssubscriptionIdOffers on a subscription
asc_create_promotional_offersubscriptionId, name, offerCode, offerMode, duration, + priceCreate an offer (a price — customerPrice/pricePointId in baseTerritory — is required for every mode)
asc_add_promotional_offer_pricepromotionalOfferId, subscriptionId, territoryAdd a discounted price for another territory
asc_delete_promotional_offerpromotionalOfferIdRemove an offer

Validation status. [VERIFY] — the offerCode attribute, the inline subscriptionPromotionalOfferPrices shape, and the standalone add-price path are inferred. If a call 400s, attach the JSON:API error body to an issue.

Subscription offer codes & win-back

Redeemable codes and lapsed-subscriber offers — the remaining subscription-offer types (introductory offers live under Subscriptions; promotional offers above).

ToolRequired inputsPurpose
asc_list_offer_codessubscriptionIdOffer codes on a subscription
asc_create_offer_codesubscriptionId, name, customerEligibilities, offerEligibility, offerMode, duration, + priceCreate an offer code (NEW/EXISTING/EXPIRED; a price is required)
asc_create_offer_code_custom_codesofferCodeId, customCode, numberOfCodesA memorable code usable N times
asc_create_offer_code_one_time_codesofferCodeId, numberOfCodes, expirationDateA batch of unique single-use codes
asc_list_win_back_offerssubscriptionIdWin-back offers on a subscription
asc_create_win_back_offersubscriptionId, referenceName, offerId, offerMode, duration, priority, eligibility window, startDate, + priceOffer for lapsed subscribers

Validation status. Write shapes cross-checked against the App Store Connect OpenAPI spec: offer codes require offerEligibility and a price; win-back offers require the customer-eligibility window (months paid + a months-since-last-subscribed range), a priority, and a startDate. One-time-use code values are downloaded from App Store Connect, not exposed per-code via the API. Not yet exercised live — if a call 400s, attach the JSON:API error body to an issue.

Provisioning / code signing

Bundle IDs, capabilities, certificates, test devices, and provisioning profiles — the developer-portal side, on the same auth as everything else.

ToolRequired inputsPurpose
asc_list_bundle_ids / asc_create_bundle_id / asc_delete_bundle_id(varies)Register/list/delete bundle IDs (platform IOS/MAC_OS/UNIVERSAL)
asc_enable_bundle_capability / asc_disable_bundle_capabilitybundleIdResourceId/capabilityIdToggle capabilities (push, iCloud, IAP, …)
asc_list_certificates / asc_create_certificate / asc_revoke_certificate(varies)Signing certs (create from a CSR)
asc_list_devices / asc_register_device(varies)Register test devices by UDID
asc_list_profiles / asc_create_profile / asc_delete_profile(varies)Provisioning profiles (bundleId + certs + devices)

Validation status. [VERIFY] — endpoints follow research/api-reference.md §14, but the CapabilityType/CertificateType/ProfileType enum spellings drift over time, so those inputs are free strings (common values documented in each tool). If a call 400s, attach the JSON:API error body to an issue.

Webhooks

Subscribe an HTTPS endpoint to app events (2024+).

ToolRequired inputsPurpose
asc_list_webhooks / asc_create_webhook / asc_update_webhook / asc_delete_webhook(varies)Manage webhooks (url, eventTypes, secret, enabled)
asc_ping_webhookwebhookIdSend a test delivery
asc_list_webhook_deliverieswebhookIdRecent delivery attempts (debugging)

Users & access

Team members and invitations. Requires an Admin key (lower roles get 403).

ToolRequired inputsPurpose
asc_list_users / asc_get_user / asc_update_user(varies)View/edit members (roles, app visibility)
asc_list_user_invitations / asc_invite_user / asc_cancel_user_invitation(varies)Manage pending invitations

Xcode Cloud

CI/CD products, workflows, and build runs.

ToolRequired inputsPurpose
asc_list_ci_products—CI products
asc_list_ci_workflows / asc_get_ci_workflowciProductId / workflowIdWorkflows
asc_start_ci_buildworkflowIdTrigger a build run (optional git ref)
asc_list_ci_build_runs / asc_get_ci_build_runworkflowId / buildRunIdBuild-run status/progress

Reporting

Sales & Finance reports are gzipped TSV (fetched via the raw-bytes path, gunzipped, and parsed to rows); Analytics reports are asynchronous. Needs the ACCESS_TO_REPORTS role (Finance reports need Finance/Admin).

ToolRequired inputsPurpose
asc_get_sales_reportvendorNumberSales & Trends report → parsed rows
asc_get_finance_reportvendorNumber, regionCode, reportDateFinance report → parsed rows
asc_request_analytics_reportappIdRequest an analytics report set (async)
asc_list_analytics_reportsrequestIdGenerated reports for a request

Game Center

ToolRequired inputsPurpose
asc_get_game_center_detailappIdThe app's Game Center detail (anchors the rest)
asc_list_achievements / asc_create_achievement / asc_set_achievement_localization(varies)Achievements + per-locale text
asc_list_leaderboards / asc_create_leaderboard / asc_set_leaderboard_localization(varies)Leaderboards + per-locale text

Alternative distribution (EU DMA)

Distributing outside the App Store in the EU — the newest, most speculative surface.

ToolRequired inputsPurpose
asc_get_alt_distribution_key / asc_create_alt_distribution_keyappId (+ publicKey)App's alt-distribution signing key
asc_list_alt_distribution_packagesappIdAlt-distribution build packages
asc_list_marketplace_domains / asc_create_marketplace_domain(varies)Marketplace domains

Validation status. All six domains are [VERIFY] — not yet exercised against live Apple traffic. The reporting filter names, the Xcode Cloud git-reference relationship, Game Center attribute shapes, and the entire alternative-distribution surface are inferred. If a call 400s, attach the JSON:API error body to an issue.

In-App Events

Time-boxed, promotable events on the product page. Flow: create → localize → upload card/details art → schedule per territory → asc_submit_for_review with {type:"appEvent", id}.

ToolRequired inputsPurpose
asc_list_app_eventsappIdEvents on an app (referenceName, badge, eventState)
asc_create_app_eventappId, referenceNameCreate the event (+ badge / priority / purpose / schedule)
asc_update_app_eventappEventIdSet territorySchedules (publish/start/end per territory) + other fields
asc_set_app_event_localizationappEventId, localeUpsert name / short / long description per locale
asc_upload_app_event_screenshotappEventLocalizationId, filePath, assetTypeCard / details-page image (reservation → PUT → commit)
asc_upload_app_event_video_clipappEventLocalizationId, filePath, assetTypeCard / details-page video clip
asc_delete_app_eventappEventIdDelete an event

Custom Product Pages

Per-audience variant pages, each with its own URL, promo text, and visuals. Flow: create → localize the draft version → attach screenshots/previews (the screenshot/preview set tools take customProductPageLocalizationId) → asc_submit_for_review with {type:"appCustomProductPageVersion", id}.

ToolRequired inputsPurpose
asc_list_custom_product_pagesappIdPages (name, shareable url, visible)
asc_create_custom_product_pageappId, nameCreate a page; returns the draft versionId
asc_get_custom_product_pagecustomProductPageIdurl + visibility + draft version + localizations
asc_set_custom_product_page_localizationversionId, localeUpsert promotional text; the returned localization id feeds the screenshot tools
asc_delete_custom_product_pagecustomProductPageIdDelete a page

Validation status. Create shapes confirmed against the OpenAPI spec; territorySchedules is fully typed. Not yet exercised live — video-clip formats and the exact pre-submission requirements (Apple wants a schedule before an event submits) are the likely first surprises.

Product Page Optimization (A/B experiments)

Test alternate screenshots/previews/icons against the baseline. Flow: create experiment → add treatment(s) → add a treatment localization → attach that treatment's visuals (the screenshot/preview set tools take experimentTreatmentLocalizationId) → asc_update_experiment with started: true.

ToolRequired inputsPurpose
asc_list_experimentsappIdExperiments (name, state, trafficProportion, dates)
asc_create_experimentappId, name, trafficProportionCreate an experiment (v2, app-level)
asc_get_experimentexperimentIdExperiment + its treatments
asc_update_experimentexperimentIdStart (started: true) / stop / rename / re-weight
asc_create_experiment_treatmentexperimentId, nameAdd a variant (+ optional appIconName)
asc_set_experiment_treatment_localizationtreatmentId, localeFind/create the localization; its id feeds the screenshot tools
asc_delete_experiment_treatmenttreatmentIdRemove a treatment
asc_delete_experimentexperimentIdDelete an experiment

Validation status. Shapes confirmed against the OpenAPI spec (v2 app-level model). Not yet exercised live — the exact gating on started: true (treatments must be complete and, if reviewRequired, approved first) is the likely first surprise.

Troubleshooting

Run apple-asc-mcp --diagnose first — it diagnoses about 80% of setup issues directly.

Authentication errors

SymptomLikely causeFix
401 NOT_AUTHORIZEDClock skew on your machineSync NTP. Apple rejects JWTs with iat in the future.
401 NOT_AUTHORIZED, was working yesterdayKey revoked or expired in App Store ConnectRe-create the key, download the new .p8, update env vars
401 NOT_AUTHORIZED, only on certain endpointsKey role too lowPromote to App Manager (or Admin/Finance for pricing/IAP)
401, JWT looks fineToken cached past expWe mint 18-min tokens with a 60s refresh lead; if you fork the code, don't loosen this — Apple's hard cap is 1199 seconds
Could not import the .p8 private key as PKCS#8 / ES256The .p8 was edited / re-saved and lost its line breaksRe-download from App Store Connect — keep the file byte-identical
credentials are not configured inside Claude Code (or another MCP client), but apple-asc-mcp --diagnose passes in the terminalThe server runs in the client's environment and doesn't inherit your shell exportsPut the three credentials in the registration's env — re-add with claude mcp add -e APP_STORE_CONNECT_KEY_ID=… -e APP_STORE_CONNECT_ISSUER_ID=… -e APP_STORE_CONNECT_PRIVATE_KEY_PATH=… -- apple-asc-mcp. See Wire into Claude Code.

Upload errors (ITMS-90xxx)

altool and the REST upload surface return Apple's structured error codes. The most common:

CodeMeaningCommon fix
ITMS-90049Bundle is missing a required key in Info.plistApple's error includes the key — usually CFBundleIcons, LSApplicationCategoryType, or NSPhotoLibraryUsageDescription
ITMS-90189Redundant binary upload — same CFBundleVersion already existsBump build number; build numbers must be unique per (bundleId, version)
ITMS-90683Missing purpose string for a usage-permission APIAdd NS<Capability>UsageDescription to Info.plist
ITMS-90161Invalid provisioning profileProfile doesn't include the App ID, or uses a wrong certificate. Re-export with -allowProvisioningUpdates and a valid ExportOptions.plist.
ITMS-90685CFBundleVersion value not greater than the previous uploadApp Store wants strictly increasing build numbers within a marketing version
ITMS-90809Use of deprecated SDK / APIApple's error names the API; address it or set manageAppVersionAndBuildNumber=false if it was a tooling-side rewrite
ITMS-91065Missing privacy manifest declarationsAdd a PrivacyInfo.xcprivacy to your bundle declaring required-reason API usage
STATE_ERROR.SCREENSHOTS_REQUIREDSubmitting a version with no screenshots in the primary localeUpload at least one set (e.g. APP_IPHONE_67) for the primary locale before submitting
STATE_ERROR.MISSING_METADATARequired localization fields emptyFill description and keywords for the primary locale

Build stuck in PROCESSING

  • Normal: 5–30 minutes. Larger bundles, watch/visionOS extensions, on-demand resources, and Apple Silicon-only Mac builds can take 60+ minutes.
  • If still PROCESSING after 60 minutes, check App Store Connect → My Apps → TestFlight → Build Activity for an error. The REST API will eventually move it to INVALID if processing fails server-side.
  • asc_wait_for_build_processing defaults to a 45-minute timeout. Bump timeoutMinutes if needed.

Screenshot rejected at commit time

If assetDeliveryState.state comes back FAILED after asc_upload_screenshot:

  • Wrong dimensions for the display type (most common). All screenshots in a set must share dimensions; see the table in §7.1 of the API reference.
  • Transparency / alpha channel — Apple rejects PNGs with alpha.
  • Interlaced PNG — also rejected.

The fix is always: regenerate the asset, delete the failed screenshot, and re-upload.

"No editable App Store Version"

Means the previous version is still in flight (e.g. IN_REVIEW). You can't create a new editable version until the current one resolves. Either wait, or asc_cancel_review_submission if you need to pull back.

Logs

Detailed request/response logs (with secrets redacted) live at ~/logs/apple-asc-mcp/<date>.log. Attaching the relevant slice to a bug report is the single most useful thing you can do.

Security & secret handling

  • The .p8 is a long-lived team-wide credential. Anyone with this file plus the Key ID and Issuer ID can act as the role you assigned. Treat it like a production API key:
    • chmod 600 ~/.appstoreconnect/private_keys/*.p8
    • Never commit it to git. A .gitignore entry for *.p8 is included in this repo.
    • Don't paste it into chat logs. The MCP redacts known secret arg names (password, apiKey, etc.) from its own logs, but it can't redact what you paste.
  • Pick the minimum role. App Manager is enough for everything in this MCP except pricing changes (Finance/Admin).
  • Rotate when in doubt. If you suspect compromise, revoke the key in App Store Connect → Integrations and create a new one. Old .p8 files become inert immediately on revocation.
  • Per-MCP-instance keys are fine. You can create multiple API keys for the same team — one per machine, one per CI environment, one per developer. Track them by name.
  • JWT scoping. Apple supports a scope claim limiting a JWT to specific endpoints. This MCP doesn't set it because the tool surface spans many endpoints; if you want defense-in-depth, fork and add a scope allowlist to auth.ts.

Comparison with fastlane / Transporter

Honest answer: fastlane is more battle-tested. It's been wrapping App Store Connect since 2014, supports IAPs and pricing in depth, and has a huge community. If you have a deterministic CI pipeline and a Ruby allergy isn't a problem, fastlane (pilot + deliver + match) is a fine choice.

Where this MCP wins:

  • Conversational. "Ship 1.4.0 with the screenshots in ~/screens/, demo creds from 1Password" reads like an instruction; the equivalent fastlane setup is hundreds of lines of Ruby.
  • One-shot snapshots. asc_release_status returns the entire submission-readiness picture in one call, designed for an LLM to reason over. fastlane gives you many small lanes you can call but no equivalent aggregator.
  • Modern API surface. Uses reviewSubmissions (the current submission flow) and /v1/buildUploads (REST-native binary upload from WWDC 2025) — both of which fastlane supports but which most blog posts haven't caught up to.
  • No Ruby. Single Node binary; works wherever Node 20 runs.

Where fastlane wins:

  • Coverage. IAPs, subscriptions, custom product pages, age ratings, Game Center — fastlane handles all of these. This MCP focuses on the release path and deliberately punts IAP/subscription metadata to v2.
  • Plugins. A decade of ecosystem.
  • Battle-testing. This MCP is alpha; fastlane has shipped tens of thousands of apps.

A reasonable hybrid: use fastlane for IAP-heavy workflows you've already automated, use this MCP for the conversational "drive a release" loop.

Known limitations

These are spec/platform constraints, not TODOs — they cannot be worked around in code:

  • No POST /v1/apps. Apple's REST API does not let you create a new App record from scratch. The first time you upload a build for a brand-new bundle ID, App Store Connect materializes the App row server-side; before that, you must register the bundle ID and create the App in App Store Connect's web UI.
  • xc_archive, xc_export_ipa, and asc_validate_ipa require macOS with Xcode. The REST upload path is cross-platform, but you still need a Mac to produce the IPA.
  • Bitcode is dead. uploadBitcode / compileBitcode keys in ExportOptions.plist are no-ops since Xcode 14.

These items are working but not yet validated against live Apple traffic — flagged in the code with [VERIFY] comments:

  • The Platform enum spelling on POST /v1/buildUploads (we use IOS / MAC_OS / TV_OS / VISION_OS, matching every other endpoint in the API; WWDC 2025 transcripts used a generic placeholder).
  • The full BuildUploadFile.assetType enum. We hardcode "BUILD" for the main IPA, which Apple's session described, but other values may exist for accompanying assets (dSYMs, etc.).

If you hit a 400 from the REST upload, set APP_STORE_CONNECT_PREFER_REST_UPLOAD=false to fall back to xcrun altool and please file an issue with the JSON:API error body — that's the fastest way to nail down the spec details.

Out of scope for v1 (will probably ship in v2):

  • In-App Purchases / Subscriptions (the API has 30+ endpoints for this; needs its own design pass).
  • App Pricing (appPriceSchedules with the v3 appPricePoints model — needs Finance/Admin role and a fair amount of territory bookkeeping).
  • App Custom Product Pages and A/B Test Experiments.
  • Age Rating Declaration full questionnaire automation (we expose read; the questionnaire is a moving target).
  • Provisioning profile / certificate management (bundleIds, profiles, certificates, devices). The API supports these and they fit the same auth/client; just not on the critical path for "ship a release."

Development

git clone https://github.com/warunacds/apple-asc-mcp
cd apple-asc-mcp
npm install

npm run build       # tsc → dist/
npm run dev         # tsx, hot path for iteration
npm run typecheck   # tsc --noEmit
npm test            # node --test --import tsx
npm run diagnose    # run the preflight against your env

Logs at ~/logs/apple-asc-mcp/<date>.log (mirrored to stderr).

Layout

src/
  index.ts          MCP server entry (stdio transport) + --diagnose CLI
  diagnose.ts       Preflight check runner
  auth.ts           ES256 JWT minter with caching
  client.ts         JSON:API REST client w/ retry, pagination, structured errors
  upload.ts         Asset reservation runner: chunked PUT + MD5 (used for screenshots, previews, builds)
  xcode.ts          xcodebuild & altool subprocess wrappers
  config.ts         Env + .p8 loader
  log.ts            Logs to stderr + ~/logs/apple-asc-mcp/
  tools/            One file per tool family; all flow into tools/index.ts → ALL_TOOLS
test/               node:test against in-process mock servers (no real Apple traffic)
research/           Reference docs from the design phase
examples/           Sample metadata + ExportOptions.plist

See CONTRIBUTING.md for the bar for new tools and tests.

License

MIT © 2026 apple-asc-mcp contributors

Sources

Full design notes are in research/api-reference.md and research/upload-pipeline.md.

Ver o original no GitHub

Bom para

Relacionados