appstore-connect-mcp

A local-only Model Context Protocol server that gives ClaudeCode (or any MCP-capable coding agent) safe access to App Store Connect only: apps, builds,TestFlight, App Store versions, metadata, App Info, screenshots, review information, age rating,availability, pricing, content rights, and review submission — enough to take a build from"already uploaded" to "submitted for review" with a single human confirmation at the end.

This project deliberately does not touch Xcode. Xcode operations (build, test, archive,source editing, SwiftUI previews) are handled by Apple's own official Xcode MCP. Claude Codeorchestrates both servers together. See CLAUDE.md for the full architecture andsecurity rules.

Claude Code
├── xcode              → Apple's official Xcode MCP (xcrun mcpbridge)
└── appstore-connect-mcp   → this project (stdio)

macOS only
stdio transport only — no HTTP server, no open ports, no external deploy target
No database
Your .p8 private key is never written into this repo or committed. It lives outside therepo (e.g. ~/.config/appstore-connect-mcp/) and is read from disk only when signing a JWT.

Requirements

macOS
Xcode 26.3+ (for the Xcode MCP side of the workflow)
Node.js (managed via mise)
pnpm (managed via mise)
mise
Claude Code
An App Store Connect Team API Key (Key ID + Issuer ID + downloaded .p8)

Setup

1. Xcode MCP (Apple's official server — not part of this repo)

claude mcp add --transport stdio xcode -- xcrun mcpbridge

In Xcode: Settings → Intelligence → Model Context Protocol → Allow external agents to useXcode tools.

Verify:

claude mcp list

2. appstore-connect-mcp

mise install
mise run install   # pnpm install

3. Credentials

Create an App Store Connect Team API Key at Users and Access → Integrations → Team Keys, noteits Key ID and Issuer ID, and download the .p8 file once (Apple only allows downloadingit once).

Store the .p8 outside this repository:

mkdir -p ~/.config/appstore-connect-mcp
chmod 700 ~/.config/appstore-connect-mcp
mv ~/Downloads/AuthKey_XXXXXXXXXX.p8 ~/.config/appstore-connect-mcp/
chmod 600 ~/.config/appstore-connect-mcp/AuthKey_XXXXXXXXXX.p8

(The key's own contents are never printed anywhere by this project — including here.)

Then set three environment variables, either by copying .env.example to .env in this repoand filling it in, or by exporting them in your shell / setting them directly in your MCP clientconfig (see below):

ASC_KEY_ID=<your Key ID>
ASC_ISSUER_ID=<your Issuer ID>
ASC_PRIVATE_KEY_PATH=~/.config/appstore-connect-mcp/AuthKey_XXXXXXXXXX.p8

.env, .p8, and anything matching credentials.*/secrets.* are gitignored — see.gitignore.

4. Verify

mise run test        # unit tests — no credentials needed
mise run typecheck
mise run build

To confirm your credentials actually authenticate, start the server (mise run dev) with theenv vars set and call asc_apps_list from Claude Code — a successful response confirms the JWTand credentials are valid end-to-end.

Registering with Claude Code

Add appstore-connect-mcp as its own MCP server, alongside xcode:

claude mcp add appstore-connect-mcp -- mise run dev --cwd /absolute/path/to/appstore-connect-mcp

Replace /absolute/path/to/appstore-connect-mcp with wherever you cloned this repo — that path isenvironment-specific and shouldn't be assumed.

If your Claude Code client doesn't support claude mcp add (e.g. a desktop app without the CLI),add an entry to its MCP config JSON instead:

{
  "mcpServers": {
    "appstore-connect-mcp": {
      "command": "mise",
      "args": ["-C", "/absolute/path/to/appstore-connect-mcp", "run", "dev"],
      "env": {
        "ASC_KEY_ID": "...",
        "ASC_ISSUER_ID": "...",
        "ASC_PRIVATE_KEY_PATH": "/Users/you/.config/appstore-connect-mcp/AuthKey_XXXXXXXXXX.p8"
      }
    }
  }
}

Use mise -C <dir> run dev (rather than a bare cwd field) if your client doesn't apply cwdto the spawned process — -C is mise's own "change directory before running" flag and doesn'tdepend on the client supporting a cwd key.

After registering, confirm both servers are visible:

claude mcp list

You should see both xcode and appstore-connect-mcp.

Tools

App identification never requires the numeric Apple app id — pass a bundle id(io.tmkch.colorvia) or app name (Colorvia) and it's resolved for you.

Tool titles are tagged [Read], [Write], or [Destructive/Release] so risk level is visibleat a glance (see CLAUDE.md for the philosophy behind this).

Tool	Class	Description
`asc_apps_list`	Read	List all apps on the account
`asc_app_get`	Read	Get one app's details
`asc_builds_list`	Read	List an app's uploaded builds
`asc_build_get`	Read	Get a single build
`asc_build_status`	Read	Get a build's processing state
`asc_build_upload`	Write	Upload a build (`.ipa`/`.pkg`) to App Store Connect
`asc_build_upload_status`	Read	Get the state of an in-progress build upload
`asc_beta_groups_list`	Read	List TestFlight beta groups
`asc_beta_group_add_build`	Write	Add a build to a TestFlight group
`asc_beta_build_localization_get`	Read	Get "What to Test" notes
`asc_beta_build_localization_update`	Write	Update "What to Test" notes
`asc_beta_build_status`	Read	Get TestFlight-specific build status
`asc_versions_list`	Read	List an app's App Store versions
`asc_version_get`	Read	Get a single App Store version
`asc_version_create`	Write	Create a new App Store version (supports `dryRun`)
`asc_version_update`	Write	Update a version's fields (supports `dryRun`)
`asc_version_select_build`	Write	Attach a build to a version (supports `dryRun`)
`asc_metadata_get`	Read	Get localized App Store metadata for a version
`asc_metadata_update`	Write	Update localized metadata (supports `dryRun`)
`asc_metadata_create_locale`	Write	Add a new metadata locale to a version (supports `dryRun`)
`asc_version_ensure`	Write	Return the version if it exists, else create it — race-safe (supports `dryRun`)
`asc_build_latest`	Read	Find the highest uploaded build number and suggest the next one
`asc_build_wait`	Read	Poll a build/build-upload until it's terminal (SUCCESS/FAILED/TIMEOUT/CANCELLED)
`asc_screenshot_sets_list`	Read	List screenshot sets (and their screenshots) for a version/locale
`asc_screenshot_upload`	Write	Upload a screenshot, creating its set if needed
`asc_screenshot_delete`	Destructive/Release	Permanently delete a screenshot
`asc_review_get`	Read	Get review contact/demo-account/notes — never returns the password
`asc_review_update`	Write	Update review contact/demo-account/notes (password write-only, supports `dryRun`)
`asc_age_rating_get`	Read	Get the age rating declaration
`asc_age_rating_update`	Write	Update the age rating declaration (supports `dryRun`)
`asc_app_info_localizations_list`	Read	List app-level localizations (name, subtitle, privacy policy)
`asc_app_info_localization_get`	Read	Get one app-level localization
`asc_app_info_localization_create`	Write	Add a new App Info locale (supports `dryRun`)
`asc_app_info_localization_update`	Write	Update an App Info locale (supports `dryRun`)
`asc_availability_get`	Read	Get which territories the app is available in
`asc_availability_update`	Write	Replace the full territory list, or `["ALL"]` (supports `dryRun`)
`asc_pricing_get`	Read	Get whether pricing is configured and whether it's free
`asc_pricing_set_free`	Write	Set the app to free (supports `dryRun`)
`asc_content_rights_get`	Read	Get the content rights declaration
`asc_content_rights_update`	Write	Update the content rights declaration (supports `dryRun`)
`asc_release_sync`	Write	Sync `.appstore/` SSOT config to App Store Connect, diff-based (supports `dryRun`)
`asc_release_preflight`	Read	Comprehensive App Review readiness check
`asc_submission_status`	Read	Get App Review status for a version
`asc_submit_for_review`	Destructive/Release	Submit a version for App Review — runs preflight first, always shows a native macOS confirmation dialog

There is intentionally no generic "call any App Store Connect endpoint" tool, and no tool thatdeletes apps or in-app purchases.

Not automatable through the public API

App Privacy Nutrition Labels (data collection / tracking responses) have no documentedpublic App Store Connect API endpoint. asc_release_preflight always reports this check asmanual_required — set it manually in App Store Connect under App Privacy.
Paid price points — asc_pricing_set_free reliably handles free apps; setting a specificpaid price is not exposed as a tool (Apple's price-schedule API has had several documentedbehavior changes on their developer forums, and a half-correct paid-pricing tool is worse thannone — see src/tools/pricing/service.ts).
Export compliance (ITSAppUsesNonExemptEncryption) is an Xcode/Info.plist-side setting;asc_release_preflight reports it when detectable on the uploaded build, but doesn't set it.
Apple Developer Program agreement acceptance, tax/banking info, and creating the app record forthe very first time all still require the App Store Connect web UI.

`asc_build_upload` / `asc_screenshot_upload` implementation notes

Both are implemented against Apple's actual published App Store Connect API schema — notguessed:

Builds use the BuildUpload / BuildUploadFile resources (App Store Connect API 4.1+):create the upload, create the file record, upload the file in the chunks specified by itsuploadOperations, then commit with an MD5 sourceFileChecksums.file checksum. Processing thencontinues on Apple's servers — poll asc_build_upload_status, then asc_builds_list.
Screenshots use the older AppScreenshotSet / AppScreenshot resources (API 1.2+), whichuse the same chunked-upload pattern but commit with a plain sourceFileChecksum MD5 stringinstead of a nested checksum object. asc_screenshot_upload creates the screenshot setautomatically if one doesn't already exist for the given locale/display type.

Both were verified field-by-field against developer.apple.com/documentation/appstoreconnectapibefore implementation (see the header comments in src/tools/uploads/service.ts andsrc/tools/screenshots/service.ts for the exact resources referenced).

SSOT config (`.appstore/`)

Instead of calling metadata/App-Info/availability/age-rating/review/pricing/content-rights toolsone at a time, an app repo can define a single source of truth that asc_release_sync reads andreconciles against App Store Connect (diff-based — only fields that actually differ get written):

.appstore/
├── appstore.yml
├── en-US/
│   ├── name.txt
│   ├── subtitle.txt
│   ├── description.txt
│   ├── keywords.txt
│   ├── promotional_text.txt
│   └── whats_new.txt
└── ja/
    └── ... (same files)

app:
  bundleId: io.tmkch.example

release:
  type: MANUAL

pricing:
  type: FREE

availability:
  territories: [JPN, USA, CAN, GBR]

review:
  signInRequired: false
  usernameEnv: APP_REVIEW_USERNAME
  passwordEnv: APP_REVIEW_PASSWORD

ageRating:
  userGeneratedContent: false
  unrestrictedWebAccess: false
  gambling: false

Secrets are referenced by environment variable name only — review.usernameEnv /review.passwordEnv, resolved from the environment at sync time. A literal review.password (orusername) key in the YAML is rejected by the schema outright. All file access is confined to<projectRoot>/.appstore/ (see src/utils/projectPath.ts) — directory traversal via .. or anunsafe locale/filename is rejected before any read happens.

Screenshots are not part of this format yet — upload them with asc_screenshot_upload directly.App Privacy is always reported as manual_required (no public API — see above).

Release flow

Xcode MCP: Build → Test
      ↓
asc_build_latest → next build number
      ↓
Xcode MCP: set version/build number → Archive → Export
      ↓
asc_build_upload → asc_build_wait (poll until VALID)
      ↓
asc_version_ensure
      ↓
asc_release_sync (or individual metadata/appInfo/availability/ageRating/pricing/contentRights tools)
      ↓
asc_version_select_build
      ↓
asc_release_preflight → must be ready: true
      ↓
asc_submit_for_review → preflight re-checked → macOS confirmation dialog → human clicks Submit

See CLAUDE.md for the full orchestration rules (what never to skip, e.g. neversubmitting with failing tests or a still-processing build).

`dryRun`

Write tools that support it accept dryRun: true and return the change as a before/after diffinstead of applying it:

{ "appId": "Colorvia", "version": "1.1", "locale": "en-US", "description": "...", "dryRun": true }

{ "dryRun": true, "action": "asc_metadata_update", "changes": [
  { "field": "description", "old": "...", "new": "..." }
] }

Development

mise run dev         # run the MCP server from source (stdio)
mise run build        # compile to dist/
mise run typecheck
mise run test          # unit tests — no App Store Connect credentials required

Unit tests never hit the real App Store Connect API — HTTP is stubbed at the fetch boundary,and JWT tests sign against a throwaway EC key generated in the test itself.

Project layout

src/
├── index.ts              # MCP entrypoint (stdio)
├── server/mcp.ts          # registers every tool group
├── auth/
│   ├── config.ts           # env var loading + .p8 file reading
│   └── jwt.ts               # ES256 Team API Key JWT signing/caching
├── asc/
│   ├── client.ts            # asc.get/post/patch/delete — not exposed as an MCP tool
│   ├── errors.ts             # AppStoreConnectError (HTTP/Reason/Suggestion), AscNetworkError
│   └── types.ts               # shared Apple JSON:API + summary types
├── tools/
│   ├── apps/ builds/ uploads/ testflight/ versions/ metadata/ screenshots/ submissions/
│   ├── review/ ageRating/ appInfo/ availability/ pricing/ contentRights/ buildWait/
│   ├── releaseSync/ releasePreflight/
│   └── each: service.ts (App Store Connect logic) + index.ts (MCP tool registration)
├── config/
│   ├── ssotSchema.ts        # zod schema for .appstore/appstore.yml
│   └── ssotLoader.ts          # reads/validates SSOT + locale files (path-confined)
├── security/confirm.ts     # osascript confirmation dialog (submit-for-review)
└── utils/
    ├── resolveApp.ts, resolveVersion.ts, resolveAppInfo.ts   # id resolution + caching
    ├── mcpResult.ts                        # toolJson/toolError helpers
    ├── dryRun.ts                            # shared dryRun diff builder
    ├── fileUpload.ts                         # chunked uploadOperations PUT + MD5 checksum
    └── projectPath.ts                         # path-traversal guard for SSOT file access
tests/                     # node:test unit tests, no live API calls

appstore-connect-mcp