appstoreconnect-mcp

# appstoreconnect-mcp

[![npm](https://img.shields.io/npm/v/@akoskomuves/appstoreconnect-mcp.svg)](https://www.npmjs.com/package/@akoskomuves/appstoreconnect-mcp)
[![CI](https://github.com/akoskomuves/appstoreconnect-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/akoskomuves/appstoreconnect-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Apple App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi). 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](#roadmap).

## Install (zero-config)

```sh
npx @akoskomuves/appstoreconnect-mcp init
```

The wizard:

1. Opens [App Store Connect → Keys](https://appstoreconnect.apple.com/access/integrations/api) 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:

```sh
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:

```json
{
  "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:

```sh
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](https://appstoreconnect.apple.com/access/integrations/api). Pricing writes need the **Admin** role; read-only operations work with **App Manager**.

| Variable | What |
| --- | --- |
| `ASC_ISSUER_ID` | Issuer UUID from the Keys page |
| `ASC_KEY_ID` | 10-character Key ID |
| `ASC_PRIVATE_KEY_PATH` | Path to your downloaded `AuthKey_XXXXXXXXXX.p8` file (`~` is expanded) |

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.

| Variable | What |
| --- | --- |
| `ASC_IAP_ISSUER_ID` | Issuer UUID from the In-App Purchase keys tab (different from `ASC_ISSUER_ID`) |
| `ASC_IAP_KEY_ID` | 10-character Key ID for the IAP key |
| `ASC_IAP_PRIVATE_KEY_PATH` | Path to the IAP signing `.p8` (`~` is expanded) |

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](https://appstoreconnect.apple.com/itc/payments_and_financial_reports) next to your team name (a numeric string like `85123456`).

| Variable | What |
| --- | --- |
| `ASC_VENDOR_NUMBER` | Default vendor number for sales/finance report downloads |

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 `offerMode`s: `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.
- `as