app-store-connect-mcp

# app-store-connect-mcp

> **The complete Model Context Protocol (MCP) server for Apple's App Store Connect API.**
> **1316 tools. 100% coverage** of every non-deprecated operation in Apple's official OpenAPI spec — TestFlight, Xcode Cloud, Game Center, App Clips, in-app purchases, subscriptions, review submissions, analytics, provisioning, and everything else Apple exposes. Works with Claude, Cursor, VS Code Copilot, Codex CLI, Gemini CLI, Windsurf, or any MCP client.

[![npm version](https://img.shields.io/npm/v/apple-app-store-connect-mcp.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/apple-app-store-connect-mcp)
[![npm downloads](https://img.shields.io/npm/dm/apple-app-store-connect-mcp.svg)](https://www.npmjs.com/package/apple-app-store-connect-mcp)
[![CI](https://github.com/devinwang/app-store-connect-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/devinwang/app-store-connect-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](package.json)
[![Tools: 1316](https://img.shields.io/badge/tools-1316-informational.svg)](#feature-matrix)
[![Spec: 4.3](https://img.shields.io/badge/App%20Store%20Connect%20API-4.3-000000.svg)](https://developer.apple.com/documentation/appstoreconnectapi)
[![MCP](https://img.shields.io/badge/MCP-compatible-9B59B6.svg)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg)](tsconfig.json)

**See also:** [`google-play-developer-mcp`](https://github.com/devinwang/google-play-developer-mcp) — the same philosophy for the Google Play Console.

---

## Table of Contents

- [Why this exists](#why-this-exists)
- [Feature matrix](#feature-matrix)
- [Quick start](#quick-start)
- [Step-by-step setup](#step-by-step-setup)
- [Register with your MCP client](#register-with-your-mcp-client)
- [Usage examples](#usage-examples)
- [Migrating from `asc-mcp` (zelentsov-dev)](#migrating-from-asc-mcp-zelentsov-dev)
- [Security](#security)
- [Design notes](#design-notes)
- [Contributing](#contributing)
- [Version history](#version-history)
- [References](#references)

---

## Why this exists

App Store Connect is huge. Apple's own OpenAPI spec currently lists **1303 operations** across 203 resource groups — TestFlight, Xcode Cloud, Game Center, App Clips, in-app purchases, subscriptions, offer codes, review submissions, alternative distribution (EU DMA), analytics, metrics, privacy manifests, provisioning, users… the list goes on.

Every community MCP covers a slice. None covers everything.

**`app-store-connect-mcp` does.**

| Property | This server | Typical community MCP |
|---|---|---|
| App Store Connect API coverage | ✅ 1300+ tools (100% of spec v4.5.1) | Partial (usually 50–150 tools) |
| Xcode Cloud | ✅ all `ciProducts` / `ciWorkflows` / `ciBuildRuns` / `ciBuildActions` / `ciArtifacts` / `ciIssues` / `ciTestResults` | ❌ |
| Game Center | ✅ achievements, leaderboards, groups, matchmaking, vocabularies | ❌ |
| App Clips | ✅ default + advanced experiences, review details, header images | ❌ |
| Review Submissions v2 | ✅ | Often still on the legacy `appStoreVersionSubmissions` |
| Alternative distribution (EU DMA) | ✅ | ❌ |
| App data usages (privacy) | ✅ | ❌ |
| Multi-account (switch between dev accounts) | ✅ local registry + per-project `ASC_ACCOUNT` pin | Usually one |
| Credential safety | No `.p8` content in repo, no keys in the process cache, strict `.gitignore` | Varies |
| Spec-driven — auto-regenerate on new spec | ✅ `npm run codegen` | ❌ |

If you drive App Store Connect with an AI assistant — submission automation, TestFlight management, IAP / subscription catalog, review triage, analytics, or Xcode Cloud orchestration — this gives the assistant the full toolbox in one install.

---

## Feature matrix

**1316 tools total (as of spec v4.5.1):**

- **6** `accounts_*` — local multi-account registry (add / list / switch / remove / update / current)
- **2** `auth_*` — `auth_status` (readiness) and `auth_revoke_cache`
- **1303** auto-generated from the official App Store Connect OpenAPI spec, one per operation, covering every resource group:
  - Apps / App Infos / App Store Versions / App Store Version Localizations / Phased Releases / Version Submissions
  - Review Submissions (v2) + Review Submission Items + App Store Review Attachments + App Store Review Details
  - TestFlight: Beta Groups, Beta Testers, Beta App Review Details/Submissions, Beta App Localizations, Beta Build Localizations, Beta License Agreements, Beta Feedback Screenshot/Crash Submissions, Beta Invitees, Builds, Build Bundles, Build Bundle File Sizes
  - Xcode Cloud: Ci Products, Ci Workflows, Ci Build Runs, Ci Build Actions, Ci Artifacts, Ci Issues, Ci Test Results, Ci Xcode Versions, Ci Mac Os Versions, Ci Scm Repositories / References / Pull Requests / Providers
  - Game Center: Achievements, Leaderboards, Leaderboard Sets, Groups, Matchmaking Queues / Rule Sets / Rules / Teams, Activities, Player Scores / Achievements, App Versions, Enabled Versions, Details, Vocabularies, plus all Localizations / Images / Releases
  - App Clips: App Clips, Default / Advanced Experiences, Default / Advanced Experience Localizations, Header Images, Advanced Experience Images, App Store Review Details
  - In-App Purchases: IAP v2, Subscriptions, Subscription Groups, Subscription Offer Codes (custom + one-time-use), Subscription Prices, Subscription Promotional Offers, Subscription Introductory Offers, Subscription Availabilities, Win-back Offers, Promoted Purchases
  - Pricing & Availability: App Prices, App Price Points, App Price Schedules, App Availabilities V2, Territories, Territory Availabilities
  - Custom Product Pages + PPO (A/B testing): App Custom Product Pages, Versions, Localizations, App Store Version Experiments V2 + Treatments + Localizations
  - Screenshots & Previews: App Screenshots, App Screenshot Sets, App Previews, App Preview Sets, App Event Screenshots, App Event Video Clips
  - Provisioning: Bundle Ids, Bundle Id Capabilities, Certificates, Devices, Profiles, Pass Type Ids
  - Users & Access: Users, User Invitations, Actors, Sandbox Testers
  - Encryption / Compliance: App Encryption Declarations + Documents, Age Rating Declarations, App Data Usages + Categories + Purposes + Data Protections + Publish State, Accessibility Declarations, End User License Agreements
  - Alternative Distribution (EU DMA): Alternative Distribution Keys, Domains, Packages, Package Versions / Variants / Deltas, Marketplace Search Details, Marketplace Webhooks
  - Analytics: Analytics Reports, Report Requests, Report Instances, Report Segments, Diagnostic Signatures
  - Metrics: App Perf, Build Perf, Power Perf, Diagnostic Logs
  - Sales & Finance: Sales Reports, Finance Reports
  - Reviews: Customer Reviews, Customer Review Responses
  - Routing App Coverages, App Categories, App Events + Localizations, Android ↔ iOS App Mapping, External Purchase Collectors…
  - Spec 4.5 additions: App Asset Libraries (images, videos, placements), In-App Purchase / Subscription / Subscription Group Versions with V2 localizations and images, Subscription Plan Availabilities, Game Center Score Moderations and Blocked Players, App Performance Overviews
- **5** hand-written helpers for flows that don't map cleanly to a single operation:
  - `asset_upload_file` — step 2 of the 3-step asset upload protocol (screenshots, previews, review attachments, IAP review screenshots, App Clip header images, Game Center images, routing app coverages)
  - `sales_reports_download` — downloads and un-gzips sales reports, returns parsed TSV
  - `finance_reports_download` — same for finance reports
  - `analytics_report_instance_wait` — poll until a report is `COMPLETED`/`FAILED`
  - `ci_build_run_wait` — poll an Xcode Cloud build run to completion

Run `auth_status`, then `apps_get_collection` to verify end-to-end.

---

## Quick start

Install from npm:

```bash
npm install -g apple-app-store-connect-mcp
```

Or run without installing:

```bash
npx -y apple-app-store-connect-mcp
```

> **About the package name.** The package on npm is `apple-app-store-connect-mcp`. After install, the command on your `$PATH` is `app-store-connect-mcp` (the bin name) — that's what your MCP client config below points at.

Then add to your MCP client config (example, Claude Code):

```json
{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp"
    }
  }
}
```

Finally, register your App Store Connect API key (details below):

```
accounts_add
  name: my-app
  keyId: AB12CD34EF
  issuerId: 69a6de70-...
  keyFile: /Users/you/.config/app-store-connect-mcp/AuthKey_AB12CD34EF.p8
```

---

## Step-by-step setup

### 1. Create an App Store Connect API key

1. Open [App Store Connect](https://appstoreconnect.apple.com/).
2. **Users and Access → Integrations → App Store Connect API**.
3. Click **Generate API Key** (requires Account Holder or Admin role).
4. Name it, choose the access level you want (Admin, Developer, Finance, Marketing, etc.), and **Generate**.
5. Copy the **Key ID** and **Issuer ID** (displayed at the top of the page).
6. Click **Download API Key**. This gives you an `AuthKey_<KEYID>.p8` file. **You only get this download once.** Store it outside any git repo, for example at `~/.config/app-store-connect-mcp/AuthKey_AB12CD34EF.p8` with `chmod 600`.

### 2. Register the key with this MCP server

Launch any MCP client that has the server configured, then call:

```
accounts_add
  name: my-app
  keyId: <the 10-char Key ID>
  issuerId: <the UUID shown above the API keys list>
  keyFile: /absolute/path/to/AuthKey_XXXXXXXXXX.p8
  description: (optional)
```

### 3. Verify

```
auth_status
```

Should return `{ source: "accounts", tokenAcquired: true, expiresAt: ... }`.

```
apps_get_collection
```

Lists the apps the key can see.

### 4. Managing multiple accounts

`