appstoreconnect-mcp

A Model Context Protocol server for the Apple App Store Connect API. Drives apps, subscriptions, pricing, and more from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Windsurf).

The first published surface is subscription pricing — including a Purchasing Power Parity rebalance flow that's already been used to schedule 120 production price changes across 65 territories on a real iOS app. New ASC domains (TestFlight, sales, screenshots, IAPs) are designed to plug in one file at a time; see Roadmap.

Install (zero-config)

npx @akoskomuves/appstoreconnect-mcp init

The wizard:

1. Opens App Store Connect → Keys so you can download a .p8 (skipped if you already have one).

2. Copies the key to ~/.appstore/ with chmod 600.

3. Asks for your Issuer ID and (auto-detected) Key ID.

4. Verifies auth with a real API call before writing anything.

5. Detects which MCP clients you have installed — Claude Code, Claude Desktop, Cursor, Windsurf — and registers itself in the ones you pick.

When something looks off later, run a read-only diagnostic:

npx @akoskomuves/appstoreconnect-mcp doctor

Manual install

If you'd rather wire it up by hand, add to ~/.claude.json (Claude Code), claude_desktop_config.json (Claude Desktop), or your client's equivalent:

{
  "mcpServers": {
    "appstoreconnect": {
      "command": "npx",
      "args": ["-y", "@akoskomuves/appstoreconnect-mcp"],
      "env": {
        "ASC_ISSUER_ID": "...",
        "ASC_KEY_ID": "...",
        "ASC_PRIVATE_KEY_PATH": "~/.appstore/AuthKey_XXXXXXXXXX.p8"
      }
    }
  }
}

Or via Claude Code's CLI:

claude mcp add appstoreconnect \
  -e ASC_ISSUER_ID=... \
  -e ASC_KEY_ID=... \
  -e ASC_PRIVATE_KEY_PATH=~/.appstore/AuthKey_XXXXXXXXXX.p8 \
  -- npx -y @akoskomuves/appstoreconnect-mcp

Related MCP server: asc-mcp

Configure

Generate an App Store Connect API key at App Store Connect → Users and Access → Integrations → Keys. Pricing writes need the Admin role; read-only operations work with App Manager.

The .p8 file is a private key — never commit it. Recommended: ~/.appstore/AuthKey_XXXXXXXXXX.p8 outside any repo.

Optional: In-App Purchase signing key

Only needed for the asc_sign_* tools (subscription offer redemption signing). Issue a second key at App Store Connect → Users and Access → Integrations → In-App Purchase — this is a separate key from the ASC API key above, generated on a different tab of the same page.

The server starts fine without these — only the asc_sign_* tools refuse with a setup message if they're missing. Set one or two but not all three and the server rejects with a clear error. Run appstoreconnect-mcp doctor to verify the key loads as a valid ES256 PKCS#8.

Optional: vendor number (sales + finance reports)

Only used by asc_get_sales_report / asc_get_finance_report. Your vendor number is account-level, shown at App Store Connect → Payments and Financial Reports next to your team name (a numeric string like 85123456).

Without it the two report tools still work — they just need vendorNumber passed per call (and their error message tells you where to find it). Note: downloading sales/finance reports requires an API key with the Admin, Finance, or Sales role.

Tools

Apps

• asc_list_apps — list apps (filter by bundleId)

• asc_get_app — fetch one app by ID

Subscriptions

• asc_list_subscription_groups — groups for an app

• asc_list_subscriptions — auto-renewable subscriptions in a group

• asc_list_subscription_prices — current price schedule per subscription

• asc_list_subscription_price_points — valid price points for a subscription in a territory. Pass nearAmount to narrow the response to the nearest tiers around a target price.

Subscription pricing (writes)

• asc_post_subscription_price — schedule a price change for one territory

• asc_delete_subscription_price — cancel a pending scheduled change

App pricing (paid non-subscription apps)

• asc_list_app_prices — current price schedule for an app, splitting manual overrides from auto-derived prices and surfacing the base territory

• asc_list_app_price_points — valid Apple price tiers for an app in a given territory (~600+ tiers per territory). Pass nearAmount (target price) and optional nearCount (default 10) to narrow the response to the nearest tiers — Apple does not support a near-amount filter server-side, so the full list is still paginated but only the nearest tiers are surfaced.

• asc_post_app_price_schedule — replace the entire price schedule (whole-schedule replace, NOT a merge — matches Apple's API). Pre-flight refuses unless at least one entry targets the base territory with no startDate, and requires explicit acknowledgeReplacesAll: true. A separate acknowledgeDeletesScheduledIfBaseChanges ack is required when changing the base territory (Apple wipes pending scheduled changes on base-change). Apps have no grandfather mechanism — new schedules activate atomically at each entry's startDate.

In-app purchases (consumables, non-consumables, non-renewing subs)

• asc_list_iaps — list IAPs for an app (v2 surface only — auto-renewable subscriptions are covered by the Subscriptions tools above). Filterable by inAppPurchaseType and state. If this returns zero rows for an app you know has IAPs, the IAPs may be legacy-only and need to be migrated in the App Store Connect web UI before they appear here.

• asc_get_iap — fetch a single IAP by ID.

• asc_list_iap_prices — current price schedule for an IAP (same shape as app prices: manual overrides + auto-derived + base territory).

• asc_list_iap_price_points — valid Apple price tiers for an IAP in a given territory. Same nearAmount / nearCount narrowing as the app and subscription price-point tools.

• asc_post_iap_price_schedule — replace the entire IAP price schedule (same whole-schedule replace semantics as asc_post_app_price_schedule: acknowledgeReplacesAll: true, base-territory entry with no startDate, base-change ack required). No grandfather mechanism — same as apps.

Subscription introductory offers

Introductory offers target new subscribers — the discounted "first window" before the regular price kicks in.

• asc_list_subscription_introductory_offers — list intro offers (free trial / pay-as-you-go / pay-up-front) configured for a subscription, across territories. Apple's "all territories" wildcard (a single offer with no territory) surfaces as TERR=(all) in the table.

• asc_get_subscription_introductory_offer — fetch one offer by ID.

• asc_post_subscription_introductory_offer — create an offer. Three offerModes: FREE_TRIAL (no price; omit pricePointId), PAY_AS_YOU_GO (charge the offer price each period for numberOfPeriods periods), PAY_UP_FRONT (single charge for the whole duration). Pass territoryId to target one market, or omit it for Apple's "all territories" wildcard (uses the literal price point in every market — no auto-FX). Server-side validation refuses PAY_* without pricePointId, PAY_AS_YOU_GO without numberOfPeriods, and endDate ≤ startDate — Apple's error is surfaced inline otherwise.

• asc_patch_subscription_introductory_offer — narrow update path: only startDate, endDate, and pricePointId can change after creation. To change mode / duration / periods, delete and re-create.

• asc_delete_subscription_introductory_offer — delete a pending or active offer. Apple refuses to delete one that is currently redeemable; PATCH endDate to today to stop it instead.

Subscription promotional offers

Promotional offers target existing or lapsed subscribers — opposite eligibility from intro offers, set by the resource type itself (no per-offer flag). Apple caps active promo offers at 10 per subscription. After creation, only the per-territory prices can be edited — name, offerCode, offerMode, duration, and numberOfPeriods are immutable.

• asc_list_subscription_promotional_offers — list promo offers configured for a subscription.

• asc_get_subscription_promotional_offer — fetch a single offer, including its per-territory prices.

• asc_list_subscription_promotional_offer_prices — list per-territory price rows attached to an offer (territory + currency + amount + price-point ID).

• asc_post_subscription_promotional_offer — create an offer (name + offerCode + mode + duration + all per-territory prices) in one atomic POST. Pre-flights Apple's 10-offer cap and offerCode collisions, refusing with a clear remedy message instead of letting Apple 409.

• asc_patch_subscription_promotional_offer_prices — update the offer's per-territory prices. Apple's wire semantic is replace (the new prices array becomes the post-state, dropping any territory not listed); the tool's mode: 'replace' | 'add' | 'remove' parameter hides the footgun — 'add' reads current prices and merges, 'remove' reads and filters.

• asc_delete_subscription_promotional_offer — DELETE → 204.

Subscription win-back offers

Win-back offers target lapsed subscribers — customers who previously subscribed and churned — and Apple surfaces them automatically to eligible customers based on the offer's eligibility rules (or through your own StoreKit messaging). This is the third offer type alongside introductory and promotional. Richer than promo offers: they add eligibility targeting, a schedule, priority, and an auto-asset intent. referenceName, offerId, duration, offerMode, periodCount, targetSubscriptionPlanType, and the prices are immutable after creation.

• asc_list_subscription_win_back_offers — list win-back offers configured for a subscription.

• asc_get_subscription_win_back_offer — fetch a single offer, including its subscription and per-territory prices.

• asc_list_subscription_win_back_offer_prices — list per-territory price rows attached to an offer (territory + currency + amount + price-point ID).

• asc_post_subscription_win_back_offer — create an offer (identity + eligibility rules + schedule + priority + all per-territory prices) in one atomic POST. Eligibility is expressed as customerEligibilityPaidSubscriptionDurationInMonths, customerEligibilityTimeSinceLastSubscribedInMonths (an { minimum, maximum? } range), and an optional customerEligibilityWaitBetweenOffersInMonths. Pre-flights offerId collisions and validates the range + endDate > startDate.

• asc_patch_subscription_win_back_offer — update the mutable attributes only: eligibility, startDate/endDate, priority, and promotionIntent. To change identity, mode, duration, periods, or prices, delete and re-create.

• asc_delete_subscription_win_back_offer — DELETE → 204.

IAP & subscription review assets

The review screenshot Apple requires before an in-app purchase or subscription can be submitted, plus the optional promotional images. Four resources, each on the same three-step upload flow as app screenshots (reserve → PUT chunks → commit), with a composite asc_upload_* tool that does all three from a local file. Wire gotcha handled for you: the IAP image relates via inAppPurchase while the IAP review screenshot uses inAppPurchaseV2.

• Images (to-many, per IAP / subscription): asc_list_{iap,subscription}_images · asc_get_* · asc_upload_* (composite) · asc_post_* / asc_patch_* (raw reserve/commit) · asc_delete_*.

• Review screenshots (to-one, per IAP / subscription): asc_get_{iap,subscription}_review_screenshot (returns the single one, or null) · asc_upload_* · asc_post_* / asc_patch_* · asc_delete_*. Because it's to-one, the upload/reserve tools refuse if one already exists — delete it first.

Subscription offer signing (in-app redemption)

The cryptographic signer that makes promo/intro offers redeemable in your iOS app via StoreKit. Uses a separate signing key from the ASC API key — issued at App Store Connect → Users and Access → Integrations → In-App Purchase. See the optional config section for env vars. Built on Apple's official @apple/app-store-server-library.

• asc_sign_promotional_offer_legacy — legacy ECDSA-concatenated signature used by StoreKit 1's SKPaymentDiscount and the original StoreKit 2 Product.PurchaseOption.promotionalOffer(offerID:keyID:nonce:signature:timestamp:) API. Returns the base64 signature plus the nonce, timestamp, and keyId for the caller to pass to StoreKit. Auto-generates a UUID nonce and current timestamp; both overridable for testing.

• asc_sign_promotional_offer — JWS v2 format introduced at WWDC 2025 (back-deployed to iOS 15). Use with StoreKit 2's newer promotional-offer purchase options. Returns the JWS compact serialization directly. transactionId (the customer's appTransactionId) is optional but strongly recommended.

• asc_sign_introductory_offer_eligibility — JWS v2 with aud="introductory-offer-eligibility". Lets you override StoreKit's default introductory-offer eligibility check (e.g. grant a returning customer another trial). New in WWDC 2025.

All signatures are valid for 24 hours from signing time — re-sign per redemption attempt rather than pre-signing and caching.

Territories

• asc_list_territories — all 175 App Store territories

PPP rebalancing

• ppp_load_index — return the bundled Apple Music Individual-plan price snapshot used as the PPP signal

• ppp_compute_proposal — compute a proposed per-territory price schedule (read-only dry-run; uses Apple Music ratios as implied PPP-FX, snaps to valid Apple price points, applies a configurable round strategy and floor). Pass resourceType: "subscription" (default) with subscriptionId, resourceType: "app" with appId for paid apps, resourceType: "iap" with iapId, resourceType: "introductoryOffer" with subscriptionId plus offerMode / duration (and numberOfPeriods for PAY_AS_YOU_GO), or resourceType: "promotionalOffer" with subscriptionId plus offerMode / duration / promoOfferName / promoOfferCode (and numberOfPeriods for PAY_AS_YOU_GO).

• ppp_apply_proposal — recompute and apply the proposal against ASC after confirming via MCP elicitation (or confirm: true for unattended use). Refuses if any row drops by more than maxDropPct (default 90%); skips territories where ASC billing currency ≠ Apple Music currency.

  • For subscriptions: per-territory subscriptionPrices POSTs, paced at maxConcurrency (default 2), retrying 429s automatically; existing subscribers grandfathered when preserveCurrentPrice: true (default).

  • For apps and IAPs: a single whole-schedule-replace POST (one HTTP call, atomic). Apps/IAPs have no grandfather mechanism — new prices activate at each entry's startDate. Requires acknowledgeDeletesScheduledIfBaseChanges: true when changing the base territory (Apple wipes pending scheduled changes on base-change).

  • For introductory offers: per-territory subscriptionIntroductoryOffers POSTs, paced at maxConcurrency. The Δ column compares the snapped offer price against the current regular sub price in that territory, so -50% means the offer is half off the sub. FREE_TRIAL is rejected (no price to compute — use asc_post_subscription_introductory_offer with territoryId omitted for a single global free trial). Intro offers are additions, not replacements — Apple returns 409 if an active offer already exists for a (sub, territory) cell, and those rows show as failed in the result table.

  • For promotional offers: one atomic POST to /v1/subscriptionPromotionalOffers creates the offer + all per-territory PPP-snapped prices in a single request. Create-only — refuses if offerCode collides with an existing offer or the sub is at Apple's 10-offer cap. FREE_TRIAL rejected (no price to compute). Same Δ-vs-current-sub-price reporting as intro offers.

Response shape

Every list/get tool returns a compact text table by default — designed for an LLM to read without burning context. Every tool also accepts:

• raw: true — return the full JSON:API payload (data, included, links, meta) for debugging or advanced use.

• maxItems: number — cap auto-pagination (default 500–1000 depending on the tool). The MCP follows links.next and merges + dedupes included resources across pages.

Sparse fieldsets (fields[type]=...) are applied per tool to avoid pulling unused attributes. The whole 175-territory price schedule comes back in one paginated call (200/page) at roughly 1/10th the size of the unfiltered payload.

Protocol support

Speaks the MCP 2026-07-28 revision and the 2025-era protocol from the same build — your client picks. There is nothing to configure either way.

On 2026-07-28 the server is stateless (no initialize handshake; capabilities come from server/discover), and the write-confirmation prompt uses multi-round-trip requests: ppp_apply_proposal returns an input_required result, your client shows the acknowledgement, and the same tool call is re-issued with your answer. Clients that don't support elicitation are told to re-run with confirm: true, exactly as before.

The proposal is recomputed on re-entry rather than carried across the round trip, so prices are re-read from App Store Connect immediately before anything is written — never reused from before you paused to consider. The cost is that an interactive apply computes twice: on a 64-territory subscription that is roughly 95s rather than 48s. Unattended runs with confirm: true never ask, so they compute once and are unaffected.

Production behavior

A few details worth knowing before running ppp_apply_proposal against a live App Store Connect account:

• Rate limit handling. Apple throttles POST endpoints around 50/min. client.request honours Retry-After headers and falls back to exponential backoff (2s → 60s, capped, up to 6 retries). A 60-territory rebalance pacing through retries finishes in about 2 minutes wall time with zero manual intervention.

• Currency-mismatch skip. If the bundled Apple Music index lists a territory in one currency (say BHD) but ASC bills your subscription in another (USD), the PPP-FX ratio breaks dimensionally. The proposal marks those rows currency-mismatch (asc=USD, am=BHD) and excludes them from the apply set. Common in Gulf USD-billed markets (BHR, KWT, OMN). Set those manually if you want to.

• Sanity floor. floorFactor (default 0.15) is a hard lower bound on per-territory drops as a fraction of the current price — guards against a stale index entry collapsing a price to near-zero. For a more conservative rebalance, pass 0.30 or 0.50.

• Sanity ceiling on drops. maxDropPct (default 90%) refuses to apply any run where a single row drops more than this. If you've ever seen Apple Music tank a market price aggressively, this catches the resulting outlier before you write it to ASC.

• Refresh the snapshot when you care. data/apple-music-prices.json is a hand-curated snapshot. Each entry is dated; the snapshot date is shown in proposal output. Pull request a refresh when Apple Music prices move and the project will fold it in.

PPP rebalancing skill

The examples/ppp-rebalance/ directory contains a Claude Code skill that wraps these tools into a Purchasing Power Parity workflow (dry-run → schedule → rollback) with the gotchas baked in.

mkdir -p ~/.claude/skills && \
  ln -s "$PWD/examples/ppp-rebalance" ~/.claude/skills/ppp-rebalance

Then ask Claude: "Rebalance my subscription prices using the ppp-rebalance skill."

Roadmap

v0.1–v1.0 cover monetization + beta distribution + the full App Store product-page surface + live promotional events + territory / rollout / export compliance + push notifications + revenue/analytics reporting + customer feedback + product-page A/B testing + runtime health/accessibility + pre-orders/real-FX + EU DMA alternative distribution: the full pricing/IAP/offers surface (subscriptions, paid apps, IAPs, intro offers, promo offers, offer-code campaigns, signers), TestFlight (builds, beta groups, beta testers, beta localizations, beta review submissions), the per-locale product-page copy (release notes, descriptions, keywords, promotional text), the release lifecycle (App Store Version write + V2 Review Submission), App Info / category / tag / search-keyword surfaces (v0.12), screenshot + preview asset upload + Custom Product Pages (v0.13), In-App Events + Promoted Purchases (v0.14), App Availability + Phased Release + Encryption Declarations (v0.15), the TestFlight feedback loop — beta feedback screenshots/crashes, build notifications, public-link recruitment criteria (v0.16), Webhooks — per-app event push with delivery history, redelivery, and test pings (v0.17), sales/finance report downloads + the Analytics Reports chain (v0.18), customer reviews — read, respond, summarizations (v0.19), App Store Version Experiments — product-page A/B tests with treatments + variant assets (v0.20), diagnostics/perf-power/accessibility surfaces (v0.21), per-territory pre-orders + real-FX PPP (v0.22), and EU DMA / alternative distribution (v1.0). The planned roadmap is complete. The rest is fertile ground for LLM-driven ops because so much App Store work is judgment-heavy text — review responses, pricing positioning — that a model can draft and a human approves.

| v1.2.0 ✓ | IAP + subscription review assets — the App Store review screenshot Apple requires before an IAP/subscription can be submitted, plus promotional images. Four resources (IAP/subscription × image/review-screenshot) on the v0.13 three-step upload flow, driven from one config table: composite asc_upload_* + raw reserve/commit/delete + reads. Images to-many, review screenshots to-one (upload refuses a duplicate). Wire gotcha handled: IAP image relates via inAppPurchase, IAP review screenshot via inAppPurchaseV2. 22 new tools. | "Attach the review screenshot to my new subscription so I can submit it." |

The v0.1→v1.0 roadmap is complete — every originally-planned surface has shipped. Post-1.0 work tracks Apple's API changes (new resources, contract drift — see scripts/audit-fieldsets.py): v1.1.0 adds win-back offers, v1.2.0 adds IAP/subscription review assets (closing the "can't submit without a review screenshot" gap).

Out of scope (Fastlane / Xcode already do these well): provisioning profiles, certificates, devices, capabilities, Game Center config.

Think of this as the LLM companion for App Store Connect ops. Fastlane is for the build/release pipeline; this is for the post-release knowledge work — release lifecycle, translation, pricing, ASO, customer feedback, in-store promotion, and analytics.

Each new domain is one file under src/domains/<name>.ts plus a register* call in src/index.ts. Contributions welcome — see CONTRIBUTING.md.

Develop

git clone https://github.com/akoskomuves/appstoreconnect-mcp.git
cd appstoreconnect-mcp
npm install
npm run dev   # tsx watch mode
npm test
npm run build

See CONTRIBUTING.md for the contributor flow (changesets, PR template, branch naming).

License

MIT © 2026 Akos Komuves