Appstoreconnect MCP

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

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_get_subscription_group — fetch one group by ID
• asc_list_subscriptions — auto-renewable subscriptions in a group
• asc_get_subscription — fetch one subscription by ID
• asc_list_subscription_prices — current price schedule per subscription. One row per territory (~175 unfiltered) — pass territoryId to narrow to one market
• 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 products (writes)

Creating the hierarchy itself — the step that used to send you to the App Store Connect web UI. Four names, only two of which customers ever see:

• asc_post_subscription_group — create the container every subscription must live in. A customer can hold only one active subscription per group, so mutually exclusive plans (Monthly vs Yearly) belong in the *same* group
• asc_patch_subscription_group — rename (referenceName is the only mutable attribute; groups cannot move between apps)
• asc_delete_subscription_group — lists the group's subscriptions first and refuses client-side naming the specific products that block the delete, instead of letting Apple return a bare 409
• asc_post_subscription — create an auto-renewable subscription. `productId` is permanent: it cannot be changed, and Apple never lets it be reused on the account — not even after the subscription is deleted. subscriptionPeriod is optional at create but required before submission; the new product starts in MISSING_METADATA and the success message lists the remaining steps
• asc_patch_subscription — name, subscriptionPeriod, familySharable, reviewNote, groupLevel. productId has no codepath here by construction. Nested offer/price arrays are deliberately unsupported — their wire semantic is *replace*, so a caller passing one offer would silently delete the rest; use the dedicated offer and price tools
• asc_delete_subscription — pre-checks state and refuses for products under review or ever approved, pointing at asc_post_subscription_availability as the way to stop selling a live product

Subscription group localizations

The customer-facing group heading — what the App Store renders above the plan choices, and what shows in Settings → Subscriptions. A group with no localizations cannot be submitted.

• asc_list_subscription_group_localizations / asc_get_subscription_group_localization
• asc_post_subscription_group_localization — name + locale, plus optional customAppName (overrides how the *app* name reads inside the subscription sheet; usually omit). Wire gotcha handled: the parent relationship key is subscriptionGroup, while Subscription calls the same parent group
• asc_patch_subscription_group_localization — name / customAppName; locale is the immutable lookup key
• asc_delete_subscription_group_localization

Subscription pricing (writes)

• asc_post_subscription_price — set the price for one territory, either the opening price or a scheduled change. Order matters, and both steps are confirmed live: territory availability → undated baseline → dated changes.
• Omit `startDate` for a subscription's first price in a territory. The opening row is the undated baseline; a dated first price is a price *change* with nothing to change from. Apple says so outright — *"Invalid startDate. Create a starting price before creating future prices."* — and distance doesn't help (1, 8 and 29 days out all 409).
• Availability must exist first. Without it even a correctly shaped undated POST fails, with a 409 that blames the price point (ENTITY_ERROR.RELATIONSHIP.INVALID → /data/relationships/subscriptionPricePoint/id). The price point is fine; Apple just can't price a territory the product isn't sold in. The tool translates both of these rather than passing the raw 409 through.
• preserveCurrentPrice defaults to true on a dated change and is omitted on a baseline, where there's no existing cohort to grandfather. The created row reads preserved: false until a newer price supersedes it; that is expected, not a grandfathering failure
• 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.
• asc_post_iap — create a consumable, non-consumable or non-renewing-subscription IAP. `productId` is permanent and never reusable on the account, even after a delete. The new IAP starts in MISSING_METADATA; the success message lists the remaining steps
• asc_patch_iap — name (internal), reviewNote, familySharable; pass null to clear. productId and inAppPurchaseType are immutable and never s