App Store Connect MCP

An MCP server that lets coding agents (Claude Code, Cursor, Codex and others) manage your apps in App Store Connect: TestFlight builds and testers, the store listing, screenshots, subscriptions, App Review submission, customer reviews and sales reports.

Apple doesn't ship an MCP server for App Store Connect. Xcode's xcrun mcpbridge covers building, testing and previews, not App Store Connect. Most community servers expose one tool per REST endpoint and leave the agent to chain them correctly. This one is built differently:

• Workflows as tools. "Ship this build to these groups with these notes" is one call, and so is "replace screenshot 3". The server handles the ordering, the waiting and the edge cases that agents get wrong.

• Safe by default. The server is read-only until you set ASC_WRITE=1. Anything destructive is a dry run until the agent confirms it, and the docs recommend a least-privilege API key.

• Reliable. Every step checks the current state first, so you can re-run a tool after a timeout or a dropped connection. Tools poll Apple's asynchronous processing, back off on rate limits, and return errors that say what to do next.

Status: 0.1. Every tool is tested against an in-memory App Store Connect that checks each request against Apple's OpenAPI spec (v4.5). The workflows have also been run against a real App Store Connect account on a sandbox app: build upload through the API, distribution, groups and testers, listing edits, the whole screenshot lifecycle (including a full set of 10 and an image Apple rejects), version prep and the review pre-flight. Submitting to App Review and Beta App Review was only dry-run, because those send the app to Apple. Please report anything that behaves differently for you.

Quick start

1. Create an API key with the App Manager role. In App Store Connect, go to Users and Access > Integrations > App Store Connect API > Team Keys and generate a key with App Manager access. Never use Admin. Download the .p8 file (Apple only lets you download it once), and note the Key ID and the Issuer ID. The full walkthrough, including where to keep the key, is in docs/api-key.md.

2. Download and build it. You need Node.js 20 or later and git.

git clone https://github.com/swlittles/app-store-connect-mcp.git ~/app-store-connect-mcp
cd ~/app-store-connect-mcp
npm ci                 # installs the exact locked dependencies and builds dist/index.js

You can clone it anywhere. The examples below assume ~/app-store-connect-mcp.

3. Check the key:

ASC_KEY_ID=YOUR_KEY_ID ASC_ISSUER_ID=YOUR_ISSUER_ID ASC_KEY_PATH=~/.appstoreconnect/AuthKey_YOUR_KEY_ID.p8 \
  node ~/app-store-connect-mcp/dist/index.js --check

It lists the apps the key can see.

4. Add it to your agent. Point the agent at dist/index.js, using absolute paths.

Claude Code:

claude mcp add asc --scope user \
  -e ASC_KEY_ID=YOUR_KEY_ID \
  -e ASC_ISSUER_ID=YOUR_ISSUER_ID \
  -e ASC_KEY_PATH=$HOME/.appstoreconnect/AuthKey_YOUR_KEY_ID.p8 \
  -- node $HOME/app-store-connect-mcp/dist/index.js

Add -e ASC_WRITE=1 when you want the agent to make changes, and -e ASC_APP_ID=com.example.app to set a default app.

Cursor (~/.cursor/mcp.json) and other clients that use the mcpServers JSON format:

{
  "mcpServers": {
    "asc": {
      "command": "node",
      "args": ["/Users/you/app-store-connect-mcp/dist/index.js"],
      "env": {
        "ASC_KEY_ID": "YOUR_KEY_ID",
        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
        "ASC_KEY_PATH": "/Users/you/.appstoreconnect/AuthKey_YOUR_KEY_ID.p8"
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.asc]
command = "node"
args = ["/Users/you/app-store-connect-mcp/dist/index.js"]
env = { ASC_KEY_ID = "YOUR_KEY_ID", ASC_ISSUER_ID = "YOUR_ISSUER_ID", ASC_KEY_PATH = "/Users/you/.appstoreconnect/AuthKey_YOUR_KEY_ID.p8" }

Updates are automatic. Each time your agent starts the server, the server checks GitHub for a newer release (at most every 30 minutes) and installs it in the background. The update is used from the next time the agent starts the server; the running server isn't interrupted. See Updates.

Trying it without cloning: npx -y github:swlittles/app-store-connect-mcp --check (with the same environment variables) downloads and builds it in npm's cache. That's fine for a quick try. For everyday use, clone it: npx rebuilds on first launch, which can be slower than an agent waits for a server to start.

This project is distributed only through GitHub. It isn't published to npm, so a package with this name on npm isn't this project.

Then ask for things in plain language:

• "What's the status of my app? Is the latest build ready for testers?"

• "Ship build 202610041200 to the Friends and Public Beta groups with the notes 'New daily puzzles, please try the hint button'."

• "Replace the third iPhone screenshot with ~/Desktop/shot-3.png."

• "Upload everything in ./fastlane/screenshots/en-US/iphone as the 6.9-inch iPhone screenshots."

• "Remove the free trial from the yearly subscription in every country."

• "Reply to this week's 1-star reviews."

• "Create version 1.2, attach the latest build, update What's New, and show me what's missing before we submit."

Related MCP server: App Store Connect MCP Server

Configuration

The key is only used to sign tokens. The server never logs it or puts it in tool output or error messages, and it only sends tokens to api.appstoreconnect.apple.com. That host is fixed and can't be overridden.

If the configuration is incomplete, the server still starts, and every tool returns an error explaining what's missing. Your client won't just show "failed to connect".

Keyword research with Apple Ads (optional)

To help pick the words for your 100-character keyword field, the server can read Apple's App Store search popularity data through the Apple Ads Platform API. It only reads: nothing here creates campaigns or spends money. Set it up with docs/apple-ads-key.md. The tools appear once the ADS_* variables are set, and they work without ASC_WRITE.

They're in the ads group, so ASC_DISABLED_TOOLS=ads hides them.

Updates

Clones of this repository update themselves:

• When: on each server start, the server checks GitHub at most every 30 minutes. It does this in the background after starting, so the agent never waits on it.

• What: with the default release channel, the newest version tag (v0.3.0, v0.4.0, …). With ASC_UPDATE_CHANNEL=main, the newest commit on main.

• How: git fetch, then switch to the new version. Then it rebuilds, which takes seconds and works offline. npm ci runs instead when dependencies changed. The new version is used from the next start.

• Safe to leave on:

  • It only moves forward to the newer version, and never touches a copy with local edits or its own commits, such as a development clone.

  • If installing or building fails, it switches back to the previous version and rebuilds it. It won't retry the failed version until a newer one is published.

  • Two servers starting at once can't both update; one waits for the next check.

• Check status: node ~/app-store-connect-mcp/dist/index.js --check prints the version and the last update result.

• Update now: node ~/app-store-connect-mcp/dist/index.js --update.

• Turn it off or pin a version: set ASC_AUTO_UPDATE=0, then pick a version yourself, for example git checkout v0.3.0 && npm ci.

Copies installed before v0.3.0 don't have the updater yet. Update those once by hand: cd ~/app-store-connect-mcp && git checkout -- package-lock.json && git fetch --tags && git checkout v0.3.0 && npm ci.

Turning tools off

There's no settings screen: the server runs in the background of your agent app. Choose its tools with two environment variables, set in the same place as the key:

• ASC_TOOLS is an allowlist. Only the tools listed are offered. Without it, every tool is offered.

• ASC_DISABLED_TOOLS is a denylist. It's applied after ASC_TOOLS.

Both take tool names and group names, separated by commas or spaces. Turned-off tools aren't shown to the agent at all, so it can't call them.

Examples:

-e ASC_TOOLS=read                                 # look, never touch
-e ASC_TOOLS=read,testflight                      # TestFlight only, plus reading
-e ASC_DISABLED_TOOLS=destructive                 # everything except deleting and submitting
-e ASC_DISABLED_TOOLS=submit_for_review,raw       # no App Review submissions, no raw API calls

If an entry isn't a known tool or group, every tool refuses to run until it's fixed. That way a typo in ASC_DISABLED_TOOLS can't leave a tool switched on. --check prints which tools are on.

ASC_WRITE still applies on top: without it, even enabled write tools only return dry-run plans. Your agent app may also let you block tools; for example, Claude Code's permissions.deny takes names like mcp__asc__submit_for_review.

Tools

Tools take an app argument, which can be an app ID, a bundle ID or a name. Results are short, readable text that includes the IDs a follow-up call needs.

Read (always available):

Workflows (these change things, so they need ASC_WRITE=1; any of them can be called with dry_run: true to see the plan):

Escape hatch: asc_request(method, path, query, body) calls any App Store Connect endpoint. GET works in read-only mode. POST, PATCH and DELETE need ASC_WRITE=1, and DELETE also needs confirm: true.

How it stays safe

• Read-only by default. Without ASC_WRITE=1, write tools refuse to change anything, but they still return a plan if called with dry_run: true.

• Destructive means dry run first. Tools that delete things (screenshots, offers, testers) or can't be taken back (submitting for review) default to dry_run: true. The agent gets the plan, shows it to you, and calls again with dry_run: false. The tools carry MCP destructiveHint and readOnlyHint annotations, so clients can ask before running them.

• Order that never leaves a gap. When replace_screenshot replaces an image, it uploads the new one, waits until Apple has processed it, puts it in place, and only then deletes the old one. If Apple rejects the image, nothing in the live listing changes. The one exception is a full set of 10. Apple won't allow an 11th screenshot even briefly, so the old one has to be deleted first, and the dry run says so. If the new image then fails, re-running the same call puts it in the old one's place.

• Least privilege. See below.

Choosing a key role

Use App Manager unless you have a reason not to. Step-by-step instructions are in docs/api-key.md.

Reports need a different role from everything else, so you can give the server two keys: an App Manager key as ASC_KEY_ID / ASC_KEY_PATH, and a Finance key as ASC_REPORTS_KEY_ID / ASC_REPORTS_KEY_PATH. download_report uses the reports key, and every other tool uses the main one. Apple doesn't let you add roles to an existing key, so create a new one.

If a tool needs more access than the key has, the error says so. Keep keys out of repositories: store the .p8 somewhere like ~/.appstoreconnect/ with chmod 600, and revoke any key you think has leaked under Users and Access.

Long-running jobs

Apple processes builds (usually 5 to 30 minutes) and images (usually seconds) asynchronously. Tools that wait take wait_minutes, and they send MCP progress notifications while they wait. When time runs out, they don't fail. They return a status such as "still processing; run distribute_build again with the same arguments". Re-running is always safe:

• distribute_build skips groups the build is already in, notes that already match, and beta reviews already submitted. It treats Apple's "already submitted" response as success.

• Screenshot tools match files to existing screenshots by MD5, so an image uploaded by an interrupted run isn't uploaded again. Each delete, reorder and commit is its own request. If a step fails partway, the error lists the steps that finished and gives the exact call that finishes the job. For replace_screenshot, that call includes the screenshot_id, because positions can shift between runs. Leftovers from broken uploads never block a set; replacing or uploading to it cleans them up.

• Bulk jobs (remove_intro_offers, add_free_trial, invite_testers) keep going past individual failures and report what succeeded, what failed and what wasn't tried. They stop early when the hourly rate limit (about 3,600 requests per key) runs low. Running them again finishes the job.

HTTP retries: the server retries GETs, PATCHes and DELETEs on 5xx errors and connection resets, with jittered exponential backoff. It retries POSTs only when Apple says the request didn't happen (429 or 503), because a reset POST may have gone through. It honors Retry-After and refreshes the token once on a 401.

Uploading builds

upload_build uploads an exported .ipa. Make one with:

xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive -destination 'generic/platform=iOS'
xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportPath build -exportOptionsPlist ExportOptions.plist

The ExportOptions.plist needs method set to app-store-connect and destination set to export. (With destination set to upload, Xcode uploads the build itself, and you can skip upload_build.)

• method: "api" (the default) uses App Store Connect's build upload API (buildUploads and buildUploadFiles, added in API 4.1). It needs no Xcode, so it works on Linux CI too.

• method: "altool" runs xcrun altool --upload-app with the same API key, on a Mac.

xcodebuild -exportArchive registers a placeholder upload with App Store Connect even when it only exports. upload_build recognizes these placeholders and ignores them.

Every upload needs a new, higher CFBundleVersion. A timestamp such as YYYYMMDDHHMM works well. Add ITSAppUsesNonExemptEncryption = NO to Info.plist if it applies to your app, and TestFlight will never ask about export compliance.

Apple's rules worth knowing

These came up when testing against the real API. The tools handle each one, but they explain why a change is refused:

• What's New can't be set on an app's first version.

• The age rating questionnaire starts with every answer empty, and Apple won't accept any change until all 21 questions are answered. update_age_rating with fill_unanswered: true answers the rest NONE/false. Check those answers with whoever owns the app.

• Once App Review details exist, every edit needs the full contact: first and last name, email, and phone with + and the country code.

• Fields are cleared with null, not an empty string. Pass "" to the tools, and they send null.

• Apple reports a wrong-size screenshot only as ASSET_FAILED, so the tools check image sizes before uploading. They also delete the rejected upload, so it doesn't take up one of the set's 10 slots.

• External testers aren't emailed until a build passes Beta App Review.

What the API can't do

These still need the App Store Connect website. This list was checked against API spec 4.5:

• The App Privacy questionnaire ("nutrition labels"). The public API has no endpoints for it.

• Creating a new app record. POST /v1/apps doesn't exist. Create the app on the website, then manage it from here.

• Agreements, tax and banking, including accepting updated Paid Apps agreements. When an agreement is missing, API calls fail with an error that this server explains.

• Export compliance documentation for apps that use non-exempt encryption.

• Paid introductory offers, which need a price point per territory. This server only covers free trials, so use asc_request for paid offers. App pricing, Game Center and in-app purchase editing are also in the API but not wrapped yet; asc_request reaches them.

Development

npm install
npm test               # unit and workflow tests against a spec-checked fake App Store Connect
npm run typecheck
npm run build          # dist/index.js

API types are generated from Apple's OpenAPI spec, which is pinned in spec/openapi.oas.json.gz. Its version and SHA-256 are in spec/VERSION.json.

• npm run spec:update downloads the latest spec from Apple and regenerates the types in src/generated/asc-api.ts.

• npm run spec:generate regenerates the types from the pinned spec.

Only the schemas listed in scripts/spec-schemas.json (and what they reference) are generated.

Tests run against test/helpers/fake-asc.ts, an in-memory App Store Connect. It supports JSON:API includes, filters, sorting, pagination, relationship endpoints and fault injection (connection resets, 409s, 429s). It also checks every request's path, method and query parameters against the pinned spec, so a typo in an endpoint fails a test. All fixture data is synthetic.

scripts/call-tool.mjs calls one tool on the built server over stdio, which is handy against a real account:

npm run build && node scripts/call-tool.mjs get_app_status '{"app": "com.example.app"}'

Live tests are opt-in. They run against a real account, ideally a sandbox app:

ASC_LIVE_TEST=1 ASC_KEY_ID=… ASC_ISSUER_ID=… ASC_KEY_PATH=… ASC_LIVE_APP_ID=… npm run test:live

They're read-only and dry runs unless you also set ASC_WRITE=1 and ASC_LIVE_WRITE=1. Then they also set and restore the promotional text of the live version.

License

MIT. See LICENSE. Not affiliated with Apple. App Store Connect and TestFlight are trademarks of Apple Inc.