Overview
asc-mcp is a Swift-based MCP server that connects a local macOS MCP client to the App Store Connect API. It exposes 514 tools across 34 App Store tool domains + 2 core domains, enabling you to automate iOS and macOS release workflows through natural language.
Configuration examples are included for Codex, Claude Code, Claude Desktop, Gemini CLI, VS Code with GitHub Copilot, Continue, Cursor, and Devin Desktop (formerly Windsurf). Client configuration is documented; release CI verifies installation, MCP initialization, and tool discovery on macOS rather than launching every third-party client.
New here? Follow the Quick Start. The remaining sections are reference material for advanced configuration, tool selection, and contributors.
Key capabilities
- Release and metadata — versions, localizations, builds, review submissions, phased rollout, and Xcode Cloud
- TestFlight and uploads — beta groups, testers, feedback, recruitment, build delivery, processing, and export compliance
- Monetization — in-app purchases, subscriptions, pricing, availability, offer codes, and promotional offers
- Marketing — screenshots, previews, custom product pages, product page optimization, and promoted purchases
- Accounts and provisioning — multiple App Store Connect teams, users, bundle IDs, devices, certificates, profiles, and capabilities
- Feedback and operations — customer reviews, webhooks, accessibility declarations, analytics, metrics, and diagnostics
- Safer automation — read-only mode, confirmation safeguards, strict pagination, and mutation recovery guidance
- Auditable API coverage — a versioned Apple OpenAPI contract and release-time drift checks
The source tree prepares 4.2.0; the installation examples below remain pinned to the last stable release until candidate acceptance and owner publication. See the migration guide for the separate Asset Library workflow.
Platform Support
asc-mcp is a local stdio server: the MCP client starts it on the same computer. A client being available on Linux or Windows does not make this Swift server cross-platform.
See Apple's Xcode system requirements for the macOS versions supported by each Xcode release.
Web and cloud sessions do not automatically inherit a local MCP configuration. Run the MCP client locally on a compatible Mac, or use a client feature that explicitly keeps execution on that Mac.
Quick Start
The recommended setup stores App Store Connect credentials once in a private local file. MCP clients then need only the path to the asc-mcp executable.
1. Install asc-mcp
brew install mint
mint install zelentsov-dev/[email protected]
~/.mint/bin/asc-mcp --version
2. Create an App Store Connect API key
- Open App Store Connect → Users and Access → Integrations → Team Keys.
- Generate a key with the least-privileged role that covers your workflow. App Manager or Admin is needed only when the corresponding operations require it.
- Download the
.p8file. Apple allows it to be downloaded only once. - Copy the Key ID and Issuer ID.
3. Save the credentials locally
Create private configuration directories, then move the downloaded .p8 file into ~/.keys/. Replace the source path and filename in the second command:
mkdir -p ~/.config/asc-mcp ~/.keys
chmod 700 ~/.config/asc-mcp ~/.keys
mv /path/to/downloaded/AuthKey_XXXXXXXXXX.p8 ~/.keys/
Create ~/.config/asc-mcp/companies.json:
{
"companies": [
{
"id": "my-company",
"name": "My Company",
"key_id": "XXXXXXXXXX",
"issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"key_path": "/Users/you/.keys/AuthKey_XXXXXXXXXX.p8"
}
]
}
Replace /Users/you with your actual home-directory path. Keep both files outside the repository and restrict access:
chmod 600 ~/.config/asc-mcp/companies.json
chmod 600 /Users/you/.keys/AuthKey_XXXXXXXXXX.p8
[!CAUTION] Never commit
companies.json, a.p8key, or raw credentials to Git. Revoke the App Store Connect key immediately if it is exposed.
4. Connect your MCP client
Choose one client. You do not need to configure every client.
Codex
codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
codex mcp list
Claude Code
claude mcp add \
--transport stdio \
--scope user \
asc-mcp \
-- ~/.mint/bin/asc-mcp
claude mcp get asc-mcp
claude mcp list
For Claude Desktop, Gemini CLI, VS Code, Continue, Cursor, and Devin Desktop, use the ready-to-copy examples in MCP Client Setup.
5. Try it
Restart a GUI client after changing its configuration, open its MCP tool list, and ask:
List my App Store Connect apps.
If the connection or request fails, see Troubleshooting.
Installation
Mint on macOS (recommended)
Mint installs the pinned release from source and keeps the executable at ~/.mint/bin/asc-mcp.
brew install mint
mint install zelentsov-dev/[email protected]
Update or reinstall the pinned release:
mint install zelentsov-dev/[email protected] --force
Stable users should install a version tag. Installing main or develop is intended only for maintainers and pre-release testing.
Build from source
Use Xcode 26.x on a compatible macOS version, or install a standalone Swift 6.2+ toolchain.
git clone https://github.com/zelentsov-dev/asc-mcp.git
cd asc-mcp
swift build -c release
The executable is .build/release/asc-mcp. If you copy it elsewhere, also copy the adjacent resource bundle:
cp .build/release/asc-mcp /usr/local/bin/asc-mcp
cp -R .build/release/asc-mcp_asc-mcp.bundle /usr/local/bin/
The bundle contains the versioned OpenAPI operation contract used by release checks.
Upgrading from an older release
Version 4.1 keeps every existing tool name, required input, projection key, and array shape. Xcode Cloud read tools now reject undocumented arguments and validate returned links, paging, relationship lineage, and included resources more strictly. New *Present projection fields distinguish Apple-omitted arrays from present empty arrays while legacy array fields remain arrays. Newly exposed nested *_limit inputs must be paired with their matching include value, and continuation calls must repeat the original request scope unchanged. The new product and workflow delete tools default to a safe preview and require the latest preview receipt plus exact inventory confirmation before permanent deletion.
Version 4 keeps every existing tool name and worker filter, but destructive Marketing and review-attachment calls now require an exact confirmation ID before any Apple request:
ppo_update_experiment also requires confirm_experiment_id when state is supplied. Calls that update only name or traffic proportion remain unchanged. After an unknown or committed_unverified mutation result, use the returned inspection action before retrying.
Remove undocumented top-level arguments from existing Marketing and review-attachment calls. Version 4 rejects unknown keys before any network request instead of silently ignoring them.
Configuration
Credentials
The default ~/.config/asc-mcp/companies.json file shown in the Quick Start is recommended because it works consistently for terminal and GUI clients without duplicating secrets in every client configuration.
For multiple companies, add more entries:
{
"companies": [
{
"id": "my-company",
"name": "My Company",
"key_id": "XXXXXXXXXX",
"issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"key_path": "/Users/you/.keys/AuthKey_XXXXXXXXXX.p8",
"vendor_number": "YOUR_VENDOR_NUMBER"
},
{
"id": "client-company",
"name": "Client Company",
"key_id": "YYYYYYYYYY",
"issuer_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
"key_path": "/Users/you/.keys/AuthKey_YYYYYYYYYY.p8"
}
]
}
vendor_number is required only for analytics_sales_report, analytics_financial_report, and analytics_app_summary. Find it in App Store Connect → Sales and Trends → Reports.
Environment variables are useful for automation, but GUI apps launched from Finder may not inherit your shell environment. The file-based setup above is simpler for most users.
Single company:
export ASC_KEY_ID=XXXXXXXXXX
export ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export ASC_PRIVATE_KEY_PATH=/Users/you/.keys/AuthKey_XXXXXXXXXX.p8
export ASC_COMPANY_NAME="My Company" # optional
export ASC_VENDOR_NUMBER=YOUR_VENDOR_NUMBER # optional, analytics only
Multiple companies:
export ASC_COMPANY_1_NAME="My Company"
export ASC_COMPANY_1_KEY_ID=XXXXXXXXXX
export ASC_COMPANY_1_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export ASC_COMPANY_1_KEY_PATH=/Users/you/.keys/AuthKey_XXXXXXXXXX.p8
export ASC_COMPANY_2_NAME="Client Company"
export ASC_COMPANY_2_KEY_ID=YYYYYYYYYY
export ASC_COMPANY_2_ISSUER_ID=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
export ASC_COMPANY_2_KEY_PATH=/Users/you/.keys/AuthKey_YYYYYYYYYY.p8
Numbering starts at 1. Each consecutive entry must provide both ASC_COMPANY_{N}_KEY_ID and ASC_COMPANY_{N}_ISSUER_ID; scanning stops at the first missing pair.
The server resolves credentials in this order:
--companies /absolute/path/to/companies.json- Constructor parameter for programmatic embedding
ASC_MCP_COMPANIES=/absolute/path/to/companies.json- Default configuration file locations, including
~/.config/asc-mcp/companies.json ASC_COMPANY_1_KEY_IDand the other numbered multi-company variablesASC_KEY_ID,ASC_ISSUER_ID, and a private-key variable for one company
MCP Client Setup
All examples below assume a Mint installation and the recommended companies.json credential file. Replace /Users/you with your actual home-directory path. GUI clients generally require an absolute executable path.
Recommended CLI registration:
codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
codex mcp list
codex mcp get asc-mcp --json
The same local MCP configuration is shared by Codex clients on that Mac. The user configuration is $CODEX_HOME/config.toml, which defaults to ~/.codex/config.toml:
[mcp_servers.asc-mcp]
command = "/Users/you/.mint/bin/asc-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true
For a project-specific setup, place the same table in .codex/config.toml; Codex loads project configuration only after the project is trusted. If you use shell credentials instead of companies.json, explicitly forward them:
env_vars = ["ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_PRIVATE_KEY_PATH"]
Restart a GUI client after changing the configuration, then use its MCP view or /mcp to confirm that asc-mcp is active. See the official Codex MCP documentation.
Register once for all local projects:
claude mcp add \
--transport stdio \
--scope user \
asc-mcp \
-- ~/.mint/bin/asc-mcp
claude mcp get asc-mcp
claude mcp list
Use --scope local for only the current project or --scope project to create a shared .mcp.json. Project servers require trust approval. Never place raw App Store Connect credentials in a committed .mcp.json.
Claude stores user and local MCP entries in ~/.claude.json; .claude/settings.json is not the global MCP registry. Use /mcp inside Claude Code to inspect or reconnect the server. See the official Claude Code MCP documentation.
Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"asc-mcp": {
"command": "/Users/you/.mint/bin/asc-mcp"
}
}
}
Quit and reopen Claude Desktop after saving the file.
Add the server to ~/.gemini/settings.json:
{
"mcpServers": {
"asc-mcp": {
"command": "/Users/you/.mint/bin/asc-mcp"
}
}
}
The default Gemini MCP timeout is intentionally retained. See the official Gemini CLI MCP documentation.
Run MCP: Add Server from the Command Palette and choose the user profile for a personal setup. For a workspace setup, create .vscode/mcp.json:
{
"servers": {
"asc-mcp": {
"type": "stdio",
"command": "/Users/you/.mint/bin/asc-mcp"
}
}
}
Confirm that you trust the local server when VS Code first starts it. Do not commit user-specific paths or secrets in a shared workspace file. See the official VS Code MCP documentation.
Continue does not use .vscode/mcp.json. Create .continue/mcpServers/asc-mcp.json in the workspace:
{
"mcpServers": {
"asc-mcp": {
"command": "/Users/you/.mint/bin/asc-mcp"
}
}
}
MCP tools are available in Continue agent mode. See the official Continue MCP documentation.
Use ~/.cursor/mcp.json for all projects or .cursor/mcp.json for one project:
{
"mcpServers": {
"asc-mcp": {
"command": "/Users/you/.mint/bin/asc-mcp"
}
}
}
Restart or refresh the MCP server from Cursor settings after editing the file. See the official Cursor MCP documentation.
Add the server to ~/.codeium/windsurf/mcp_config.json. This example enables a 72-tool release subset, below Cascade's 100-tool limit:
{
"mcpServers": {
"asc-mcp": {
"command": "/Users/you/.mint/bin/asc-mcp",
"args": [
"--workers",
"apps,builds,export_compliance,versions,reviews"
]
}
}
}
You can also disable individual tools in the client. Server-side worker filtering is recommended because it keeps the active catalog predictable. See the official Devin Desktop MCP documentation.
[!IMPORTANT]
commandmust point to the real executable. GUI clients often do not inherit shell aliases, PATH changes, or environment variables. Use an absolute path and prefer the defaultcompanies.jsoncredential file.
Worker Filtering
The server exposes 514 tools across 34 App Store tool domains + 2 core domains. Some MCP clients impose a tool limit; Cascade in Devin Desktop currently allows 100 active tools. Use the 36 --workers filter keys to enable only the workers you need:
# Only load apps, builds, and version lifecycle tools
asc-mcp --workers apps,builds,versions
# App Store release preparation subset (99 tools, including always-on and build sub-workers)
asc-mcp --workers apps,accessibility,builds,export_compliance,versions,app_info,screenshots
# TestFlight review helpers can be loaded separately (49 tools)
asc-mcp --workers apps,builds,beta_app,pre_release
# Monetization focus
asc-mcp --workers apps,iap,subscriptions,pricing,promoted,review_submissions
company and auth workers are always enabled regardless of the filter (they provide core multi-account and authentication functionality).
When builds is enabled, it automatically includes build_processing and build_beta sub-workers.
Read-Only Mode
Use --read-only when you want safe inspection without App Store Connect mutations:
asc-mcp --read-only
asc-mcp --read-only --workers apps,builds,reviews,analytics
In this mode, read tools such as *_list, *_get, *_search, *_status, *_verify, *_parse, *_triage, auth_*, analytics, and metrics remain available. Tools that can create, update, upload, submit, release, delete, revoke, clear, cancel, or otherwise mutate App Store Connect are blocked before their worker handler runs. company_switch remains available because it changes only the local active company context.
OpenAPI Contract and Drift Tooling
Use the operation-contract command to compare the actual credential-free WorkerManager catalog with the semantic manifest and the pinned Apple App Store Connect OpenAPI specification. The production manifest records exact Apple operationId, HTTP method, path, invocation-scoped input bindings, typed fixed values, response lineage, local workflows, implementation state, deprecated aliases, and deliberately deferred operations. The command does not load App Store Connect credentials or start the MCP server.
rm -rf /tmp/asc-openapi
mkdir -p /tmp/asc-openapi
curl -L --fail -o /tmp/asc-openapi/spec.zip \
https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
spec_entry="$(unzip -Z1 /tmp/asc-openapi/spec.zip | grep -E '(^|/)openapi\.oas[^/]*\.json$')"
test "$(echo "$spec_entry" | grep -c .)" -eq 1
unzip -p /tmp/asc-openapi/spec.zip "$spec_entry" > /tmp/asc-openapi/openapi.oas.json
swift run asc-mcp openapi-contract-check \
--spec /tmp/asc-openapi/openapi.oas.json \
--json-output /tmp/asc-openapi/operation-contract.json \
--markdown-output /tmp/asc-openapi/operation-contract.md \
--strict
The manifest is pinned to Apple API 4.5.1 by version, SHA-256, path count, and operation count. It maps 503 Apple operations, explicitly defers 431, and scopes out 369, accounting for all 1,303 operations. Required CI checks the committed snapshot reproducibly. A separate latest-Apple comparison produces a semantic drift report and blocks publication until changes are reviewed. Contract CI fails when a mapped operation moves or disappears, a public tool or worker drifts from the manifest, an input field loses its binding, response lineage becomes invalid, or a deferred decision expires. Unexposed optional Apple parameters are warnings so they remain visible in the generated backlog.
Manifest schema v2 also accounts for every optional Apple query and request-body input as publicly bound, internally controlled, intentionally omitted with a reviewed reason, or still unclassified. The checked-in optionalInputCoveragePin records the exact current totals and a SHA-256 digest of the sorted input identities and dispositions; --strict rejects a missing pin or any count- or identity-level drift. The pin makes phased remediation auditable and regression-safe, but it is not a claim that every optional Apple input is already public. The v4.1.3 pin is 2,905 total: 1,122 bound, 40 internally controlled, 1,743 intentionally omitted, and 0 unclassified. Its identity SHA-256 is c975f4e4eebb62ec87864a73fbf72bb8841f644108e54e6ffb25168bcf2a2766.
--strict is the merge- and tag-time release gate. Every declared target or broken tool remains an error in reports, and a regression test pins their exact state. The current baseline has no target or broken implementations and no implementation drift, so any implementation that leaves asBuilt, any structural contract error, or any optional-input coverage drift blocks both merges and releases. --structural-strict remains available only for local phased remediation work.
This gate proves operation identity, top-level MCP field ownership, required Apple inputs, typed internal values, and response source/pointer lineage. Full MCP type/enum/range parity and complete typed response schemas remain separate optimization phases; mapping status does not certify Apple account permissions or successful real-world acceptance.
The older openapi-coverage command remains available for the high-level domain report in ASC-OPENAPI-COVERAGE-GENERATED.md. The operation contract is the authoritative release gate.
Available worker names:
Tool Catalog Size
When an MCP client eagerly loads every tool definition, the approximate schema footprint is:
Heaviest workers: Subscriptions (99 tools), InAppPurchases (59 tools), Xcode Cloud (42 tools), Screenshots (19 tools), Provisioning (17 tools).
Exact cost depends on the MCP host's serialization, tokenizer, and tool-discovery strategy. Modern clients may defer schemas until they are needed. Use --workers when the client enforces a tool limit or when you want a smaller, more focused catalog.
Available Tools
514 tools organized across 34 App Store tool domains + 2 core domains (use the 36 --workers filter keys — see Worker Filtering):
Compound uploads retain the same lowercase MD5 fingerprint from reservation through recovery. Explicit resume and recovered-continuation instructions carry expected_md5; the next invocation verifies a fresh immutable snapshot against it before any Apple request or transfer. An existing reservation already marked UPLOAD_COMPLETE or COMPLETE is accepted only when Apple's sourceFileChecksums.file MD5 matches that snapshot; missing, unsupported, or mismatched evidence is retained for inspection without another transfer, commit, or delete. Presigned operations retry only when their method is PUT; redirects, POST, and unknown methods are not replayed. If an ambiguous create is uniquely recovered, the workflow stops and returns its resource ID for explicit continuation. Transfer credentials stay redacted unless include_sensitive_details is explicitly enabled on a direct read.
Includes tester list/search/get/create/delete, app relationships, invitations, beta group assignment, build assignment, and app removal tools.
The legacy product-scoped localization, submission, and image tools remain callable for compatibility. Apple 4.4.1 deprecates iap_list_localizations, iap_create_localization, iap_update_localization, iap_delete_localization, iap_submit_for_review, iap_upload_image, iap_get_image, iap_delete_image, and iap_list_images; successful responses identify the versioned replacement tools. For localization creation, promotional image upload, and review submission, first use iap_list_versions, call iap_create_version only when a new metadata version is needed, and pass that version ID to the downstream versioned tool. These compatibility calls never create or select a version automatically.
If Apple may have accepted a version or version-localization create but the response is lost or cannot be decoded, the tool returns write_outcome: not_confirmed and retrySafe: false with the requested identity plus list/get inspection steps. Inspect before retrying to avoid duplicate metadata resources.
Includes subscription and group metadata versions, version-owned localizations and images, plan-type-aware availability, territory-aware prices, price points and adjusted equalizations, promoted purchase reads, inventory/pricing helpers, intro offers, promotional offers, offer codes, one-time/custom codes, win-back offers, and review screenshots. All former public offer_codes_*, intro_offers_*, promo_offers_*, and winback_* functionality is exposed through subscriptions_*.
Apple 4.4.1 also deprecates the legacy product- or group-scoped localization, image, and submission tools. They remain callable for compatibility, return explicit replacement guidance on success, and never create or select a metadata version automatically. New integrations should use subscriptions_create_version or subscriptions_create_group_version, the corresponding version-localization/image tools, and the generic review_submissions_* workflow.
Subscription version, group-version, localization, and plan-availability creates use the same non-idempotent recovery contract: an ambiguous Apple write returns write_outcome: not_confirmed, retrySafe: false, the requested fingerprint, and deterministic collection/get inspection guidance.
The following names remain available for compatibility, but Apple 4.4.1 deprecates their legacy subscriptionAvailability resource in favor of plan-type-aware subscriptionPlanAvailabilities:
Includes pre-release version listing, details, and associated builds.
Includes beta license agreement list, get, and update.
Includes app info list/get/update, app info localizations, and EULA get/create/update tools.
Includes territories, availability, price points, price schedules, and App Store availability v2 tools.
Includes team member list/get/update/remove, invitations, visible apps, and visible app relationship updates.
Includes in-app event CRUD plus event localization list/create/update/delete.
Includes sales, financial, app summary, analytics report request, report, instance, snapshot, and segment tools.
Includes App Store review attachment upload, get, delete, and list tools.
review_submissions_add_item reports success only when Apple's response confirms a valid item ID and exactly the requested relationship name, JSON:API type, and resource ID. Any mismatch is returned as an unconfirmed write with submission and item-list recovery steps.
Read the migration and recovery guide before applying changes. Upload, placement and review are separate operations; published-placement changes are outside this candidate's acceptance scope.
Usage Examples
Complete Release Workflow
You: "Release version 2.2.0 of my app with build 456"
Claude will:
1. app_versions_create(app_id, platform: "IOS", version_string: "2.2.0")
2. app_versions_attach_build(version_id, build_id)
3. app_versions_set_review_details(version_id, contact_email: "...")
4. app_versions_submit_for_review(version_id)
5. app_versions_create_phased_release(version_id) # after approval
TestFlight Distribution
You: "Create a beta group 'External Testers' and distribute the latest build"
Claude will:
1. beta_groups_create(app_id, name: "External Testers")
2. builds_list(app_id, limit: 1) # find latest
3. builds_set_beta_localization(build_id, locale: "en-US", whats_new: "...")
4. beta_groups_add_testers(group_id, tester_ids: [...])
Review Management
You: "Show me all 1-star reviews from the last week and draft responses"
Claude will:
1. reviews_list(app_id, rating: 1, sort: "-createdDate", limit: 50)
2. reviews_create_response(review_id, response_body: "...") # for each
Multi-Company Workflow
You: "Switch to ClientCorp and check their latest build status"
Claude will:
1. company_switch(company: "ClientCorp")
2. apps_list(limit: 5)
3. builds_list(app_id, limit: 1)
4. builds_get_processing_state(build_id)
API Constraints
Architecture
Sources/asc-mcp/
├── EntryPoint.swift # Entry point, --workers filtering
├── Core/
│ ├── Application.swift # MCP server setup & initialization
│ └── ASCError.swift # Custom error types
├── Helpers/ # JSON formatting, pagination, safe helpers
├── Models/ # API request/response models
│ ├── AppStoreConnect/ # Apps, versions, localizations
│ ├── Builds/ # Builds, beta details, beta groups
│ ├── AppLifecycle/ # Version lifecycle models
│ ├── InAppPurchases/ # IAP models
│ ├── Subscriptions/ # Subscriptions, offer codes, win-back
│ ├── Marketing/ # Screenshots, custom pages, PPO, promoted
│ ├── Metrics/ # Performance metrics, diagnostics
│ ├── Analytics/ # Sales/financial reports
│ ├── Provisioning/ # Bundle IDs, devices, certificates
│ ├── Shared/ # Shared upload/image types
│ └── ... # AppEvents, AppInfo, Pricing, Users
├── Services/
│ ├── HTTPClient.swift # Actor-based HTTP with retry logic
│ ├── JWTService.swift # ES256 JWT token generation
│ └── CompaniesManager.swift # Multi-account management
└── Workers/ # MCP tool implementations (40 Swift worker classes + MainWorker router)
├── MainWorker/WorkerManager # Central tool registry & routing
├── CompaniesWorker/ # company_* tools
├── AuthWorker/ # auth_* tools
├── AppsWorker/ # apps_* tools
├── AccessibilityWorker/ # accessibility_* tools
├── WebhooksWorker/ # webhooks_* tools
├── XcodeCloudWorker/ # xcode_cloud_* tools
├── BuildsWorker/ # builds_* tools
├── BuildUploadsWorker/ # build_uploads_* tools
├── BuildProcessingWorker/ # builds_*_processing tools
├── ExportComplianceWorker/ # export_compliance_* tools
├── BuildBetaDetailsWorker/ # builds_*_beta_* tools
├── AppLifecycleWorker/ # app_versions_* tools
├── ReviewsWorker/ # reviews_* tools
├── BetaGroupsWorker/ # beta_groups_* tools
├── BetaFeedbackWorker/ # beta_feedback_* tools
├── BetaTestersWorker/ # beta_testers_* tools
├── InAppPurchasesWorker/ # iap_* tools
├── SubscriptionsWorker/ # subscriptions_* tools
├── OfferCodesWorker/ # subscriptions offer-code tools
├── IntroductoryOffersWorker/ # subscriptions intro-offer tools
├── PromotionalOffersWorker/ # subscriptions promotional-offer tools
├── WinBackOffersWorker/ # subscriptions win-back tools
├── SandboxTestersWorker/ # sandbox_* tools
├── BetaAppWorker/ # beta_app_* tools
├── PreReleaseVersionsWorker/ # pre_release_* tools
├── BetaLicenseAgreementsWorker/ # beta_license_* tools
├── ProvisioningWorker/ # provisioning_* tools
├── AppInfoWorker/ # app_info_* tools
├── PricingWorker/ # pricing_* tools
├── UsersWorker/ # users_* tools
├── AppEventsWorker/ # app_events_* tools
├── AnalyticsWorker/ # analytics_* tools
├── ScreenshotsWorker/ # screenshots_* tools
├── CustomProductPagesWorker/ # custom_pages_* tools
├── ProductPageOptimizationWorker/ # ppo_* tools
├── PromotedPurchasesWorker/ # promoted_* tools
├── ReviewAttachmentsWorker/ # review_attachments_* tools
├── ReviewSubmissionsWorker/ # review_submissions_* tools
└── MetricsWorker/ # metrics_* tools
Design Principles
- Swift 6 strict concurrency — all workers and services are
Sendable, proper actor isolation - Actor-based HTTP client — thread-safe with exponential backoff and retry logic
- Prefix-based routing —
WorkerManagerroutes tool calls by name prefix (zero config) - Minimal dependencies — only the MCP Swift SDK
Troubleshooting
- Run
~/.mint/bin/asc-mcp --versionto verify the installation independently of the MCP client. - Verify that the MCP client uses the absolute path to the installed executable.
- For Codex, run
codex mcp listandcodex mcp get asc-mcp --json. - For Claude Code, run
claude mcp get asc-mcpandclaude mcp list. - Check either the configured
companies.jsonfile or the environment variables used by your chosen setup. - Ensure every
.p8key path is absolute and the file exists. - Restart GUI clients after changing their MCP configuration, then inspect the client's MCP output log.
- Verify your Key ID and Issuer ID match what's shown in App Store Connect
- Ensure the
.p8file is the original download (not modified) - Check that the API key hasn't been revoked
- JWT tokens auto-refresh, but if the key is invalid, all requests will fail
apps_update_metadata sends the metadata PATCH to App Store Connect after local text, locale, and URL validation. Apple decides whether the current version state is editable. Rejected and metadata-rejected versions can be edited and resubmitted; published, in-review, or otherwise locked versions may return an Apple API error.
Use builds_get_processing_status to inspect the current processing state and builds_check_readiness to verify App Store/TestFlight readiness. Apple's build processing typically takes 5-30 minutes but can be longer during peak times.
The HTTP client automatically retries with exponential backoff on 429 responses. If you consistently hit limits, reduce the frequency of API calls or use pagination with smaller page sizes.
Getting Help
Before opening a report, search the existing issues. If the problem is new, open an issue and include:
- macOS version and installation method;
- MCP client name and version;
- the selected
--workersvalue, if any; - the exact error message and the smallest reproducible request.
Remove Key IDs, Issuer IDs, private keys, signed URLs, tokens, and account data from logs before posting them. Report security vulnerabilities privately by following SECURITY.md. For code contributions, see CONTRIBUTING.md.
Development
Building
swift build # Debug build
swift build -c release # Release build (optimized)
swift package clean # Clean build artifacts
Test Mode
.build/debug/asc-mcp --test # Runs built-in integration tests
Adding a New Tool
- Create handler method in the appropriate
Worker+Handlers.swift - Add tool definition in
Worker+ToolDefinitions.swift - Register in worker's
getTools()method - Add routing case in worker's
handleTool()switch - The
WorkerManagerauto-routes by prefix — no changes needed there
Adding a New Worker
- Create directory:
Workers/MyWorker/ - Create 3 files:
MyWorker.swift,MyWorker+ToolDefinitions.swift,MyWorker+Handlers.swift - Add worker property and initialization in
WorkerManager.swift - Add routing rule in
WorkerManager.registerWorkers() - Add
getMyTools()helper method
Contributing
We welcome contributions! See Contributing Guide for details.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Acknowledgments
- Model Context Protocol — the protocol specification and Swift SDK
- App Store Connect API — Apple's official REST API
This is an unofficial, community-maintained tool and is not affiliated with or endorsed by Apple Inc.
