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