App Store Connect MCP Server

App Store Connect MCP 服务

一个用于 App Store Connect API 的本地模型上下文协议服务。
可在 macOS 上通过 Codex、Claude 和其他 MCP 客户端管理应用、构建版本、TestFlight、审核等。

概述

asc-mcp 是一个基于 Swift 的 MCP 服务，可将本地 macOS MCP 客户端连接到 App Store Connect API。它提供覆盖 34 个 App Store 工具领域和 2 个核心领域的 514 个工具，让你能够通过自然语言自动化 iOS 和 macOS 发布工作流。

其中包含适用于 Codex、Claude Code、Claude Desktop、Gemini CLI、VS Code with GitHub Copilot、Continue、Cursor 和 Devin Desktop（原名 Windsurf）的配置示例。文档介绍了客户端配置；发布 CI 会在 macOS 上验证安装、MCP 初始化和工具发现，而不会启动每个第三方客户端。

初次使用？请参阅快速入门。其余章节是有关高级配置、工具选择和贡献者的参考资料。

主要功能

• 发布和元数据 — 版本、本地化内容、构建版本、审核提交、分阶段发布和 Xcode Cloud
• TestFlight 和上传 — 测试版群组、测试人员、反馈、招募、构建版本交付、处理和出口合规
• 变现 — App 内购买项目、订阅、定价、供应情况、优惠代码和促销优惠
• 营销 — 屏幕截图、预览、自定产品页面、产品页面优化和推广购买
• 账户和配置 — 多个 App Store Connect 团队、用户、Bundle ID、设备、证书、描述文件和功能
• 反馈和运营 — 客户评价、Webhook、无障碍声明、分析、指标和诊断
• 更安全的自动化 — 只读模式、确认保护、严格分页和变更恢复指南
• 可审计的 API 覆盖范围 — 版本化的 Apple OpenAPI 合约和发布时偏差检查

源代码树正在准备 4.2.0；下方的安装示例仍固定在上一个稳定版本，直到候选版本获批并由维护者发布。有关单独的资源库工作流，请参阅迁移指南。

平台支持

asc-mcp 是一个本地 stdio 服务：MCP 客户端会在同一台电脑上启动它。客户端可在 Linux 或 Windows 上使用，并不意味着这个 Swift 服务支持跨平台。

请参阅 Apple 的 Xcode 系统要求，了解各个 Xcode 版本支持的 macOS 版本。

Web 和云端会话不会自动继承本地 MCP 配置。请在兼容的 Mac 上本地运行 MCP 客户端，或使用明确将执行保留在该 Mac 上的客户端功能。

快速开始

建议将 App Store Connect 凭据一次性保存在本地私密文件中。之后，MCP 客户端只需配置 asc-mcp 可执行文件的路径。

1. 安装 asc-mcp

brew install mint
mint install zelentsov-dev/[email protected]
~/.mint/bin/asc-mcp --version

2. 创建 App Store Connect API 密钥

1. 打开 App Store Connect → 用户与访问 → 集成 → 团队密钥。
2. 生成一个权限尽可能小、但足以满足工作流需求的密钥。只有在相应操作需要时，才需要 App Manager 或 Admin 角色。
3. 下载 .p8 文件。Apple 只允许下载一次。
4. 复制 Key ID 和 Issuer ID。

3. 在本地保存凭据

创建私密配置目录，然后将下载的 .p8 文件移至 ~/.keys/。替换第二条命令中的源路径和文件名：

mkdir -p ~/.config/asc-mcp ~/.keys
chmod 700 ~/.config/asc-mcp ~/.keys
mv /path/to/downloaded/AuthKey_XXXXXXXXXX.p8 ~/.keys/

创建 ~/.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"
    }
  ]
}

将 /Users/you 替换为你的实际主目录路径。将这两个文件保存在仓库之外，并限制访问权限：

chmod 600 ~/.config/asc-mcp/companies.json
chmod 600 /Users/you/.keys/AuthKey_XXXXXXXXXX.p8

注意

切勿将 companies.json、.p8 密钥或原始凭据提交到 Git。如果密钥泄露，请立即撤销 App Store Connect 密钥。

4. 连接 MCP 客户端

选择一个客户端即可，无需配置所有客户端。

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

对于 Claude Desktop、Gemini CLI、VS Code、Continue、Cursor 和 Devin Desktop，请使用 MCP 客户端设置中的可直接复制示例。

5. 试用

更改配置后，重启图形界面客户端，打开其 MCP 工具列表，然后询问：

List my App Store Connect apps.

如果连接或请求失败，请参阅故障排除。

安装

在 macOS 上使用 Mint（推荐）

Mint 会从源代码安装指定版本的发布版本，并将可执行文件保存在 ~/.mint/bin/asc-mcp。

brew install mint
mint install zelentsov-dev/[email protected]

更新或重新安装指定版本的发布版本：

mint install zelentsov-dev/[email protected] --force

稳定版用户应安装版本标签。安装 main 或 develop 仅适用于维护者和预发布测试。

从源代码构建

请在兼容的 macOS 版本上使用 Xcode 26.x，或安装独立的 Swift 6.2+ 工具链。

git clone https://github.com/zelentsov-dev/asc-mcp.git
cd asc-mcp
swift build -c release

可执行文件位于 .build/release/asc-mcp。如果将它复制到其他位置，也请一并复制旁边的资源包：

cp .build/release/asc-mcp /usr/local/bin/asc-mcp
cp -R .build/release/asc-mcp_asc-mcp.bundle /usr/local/bin/

该资源包包含发布检查使用的、带版本的 OpenAPI 操作契约。

从旧版本升级

配置

凭据

推荐使用快速开始中展示的默认 ~/.config/asc-mcp/companies.json 文件，因为它对终端和 GUI 客户端都能一致地工作，而无需在每个客户端配置中重复存放密钥。

对于多个公司，请添加更多条目：

{
  "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 仅对 analytics_sales_report、analytics_financial_report 和 analytics_app_summary 为必需。可在 App Store Connect → Sales and Trends → Reports 中找到它。

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

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

MCP 客户端设置

以下所有示例均假设使用 Mint 安装以及推荐的 companies.json 凭据文件。请将 /Users/you 替换为你实际的用户主目录路径。GUI 客户端通常需要绝对可执行文件路径。

codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
codex mcp list
codex mcp get asc-mcp --json

[mcp_servers.asc-mcp]
command = "/Users/you/.mint/bin/asc-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

env_vars = ["ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_PRIVATE_KEY_PATH"]

claude mcp add \
  --transport stdio \
  --scope user \
  asc-mcp \
  -- ~/.mint/bin/asc-mcp

claude mcp get asc-mcp
claude mcp list

{
  "mcpServers": {
    "asc-mcp": {
      "command": "/Users/you/.mint/bin/asc-mcp"
    }
  }
}

{
  "mcpServers": {
    "asc-mcp": {
      "command": "/Users/you/.mint/bin/asc-mcp"
    }
  }
}

{
  "servers": {
    "asc-mcp": {
      "type": "stdio",
      "command": "/Users/you/.mint/bin/asc-mcp"
    }
  }
}

{
  "mcpServers": {
    "asc-mcp": {
      "command": "/Users/you/.mint/bin/asc-mcp"
    }
  }
}

{
  "mcpServers": {
    "asc-mcp": {
      "command": "/Users/you/.mint/bin/asc-mcp"
    }
  }
}

{
  "mcpServers": {
    "asc-mcp": {
      "command": "/Users/you/.mint/bin/asc-mcp",
      "args": [
        "--workers",
        "apps,builds,export_compliance,versions,reviews"
      ]
    }
  }
}

重要

command 必须指向真实的可执行文件。GUI 客户端通常不会继承 shell 别名、PATH 更改或环境变量。请使用绝对路径，并优先使用默认的 companies.json 凭据文件。

工作器过滤

该服务在 34 个 App Store 工具域和 2 个核心域中公开 514 个工具。部分 MCP 客户端会限制工具数量；Devin Desktop 中的 Cascade 目前允许启用 100 个工具。使用 36 个 --workers 过滤键，仅启用所需的工作器：

# 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 和 auth 工作器都始终启用（它们提供核心的多账户和身份验证功能）。

启用 builds 后，会自动包含 build_processing 和 build_beta 子工作器。

只读模式

需要安全检查且不修改 App Store Connect 时，请使用 --read-only：

asc-mcp --read-only
asc-mcp --read-only --workers apps,builds,reviews,analytics

在此模式下，*_list、*_get、*_search、*_status、*_verify、*_parse、*_triage、auth_*、分析和指标等读取工具仍可用。能够创建、更新、上传、提交、发布、删除、撤销、清除、取消或以其他方式修改 App Store Connect 的工具，会在其工作器处理程序运行前被拦截。company_switch 仍可用，因为它只会更改本地活动公司的上下文。

OpenAPI 契约与漂移工具

使用操作契约命令，将实际的无凭据 WorkerManager 目录与语义清单以及固定版本的 Apple App Store Connect OpenAPI 规范进行比较。生产清单记录精确的 Apple operationId、HTTP 方法、路径、按调用范围限定的输入绑定、带类型的固定值、响应沿袭、本地工作流、实现状态、已弃用别名以及有意延后的操作。该命令不会加载 App Store Connect 凭据，也不会启动 MCP 服务。

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

该清单按版本、SHA-256、路径数和操作数固定为 Apple API 4.5.1。它映射 503 个 Apple 操作，明确延后 431 个，并将 369 个排除在范围之外，涵盖全部 1,303 个操作。必需的 CI 检查会以可复现的方式验证已提交的快照。单独的最新 Apple 版本比较会生成语义漂移报告，并在变更经过审查前阻止发布。如果映射的操作发生变化或消失、公开工具或工作器偏离清单、输入字段失去绑定、响应沿袭变为无效，或延后的决策过期，契约 CI 都会失败。未公开的可选 Apple 参数会产生警告，以便它们继续显示在生成的待办清单中。

清单架构 v2 还会将每个可选 Apple 查询输入和请求正文输入标记为已公开绑定、由内部控制、因经过审查的原因而有意省略，或尚未分类。签入的 optionalInputCoveragePin 记录当前的精确总数，以及按输入标识和处理方式排序后生成的 SHA-256 摘要；--strict 会拒绝缺失固定值的情况，或任何数量级或标识级别的漂移。该固定值使分阶段修复过程可审计且能防止回归，但这并不表示每个可选 Apple 输入都已公开。v4.1.3 固定值的总数为 2,905：其中 1,122 个已绑定、40 个由内部控制、1,743 个有意省略，0 个尚未分类。其标识 SHA-256 为 c975f4e4eebb62ec87864a73fbf72bb8841f644108e54e6ffb25168bcf2a2766。 --strict 是合并和打标签时的发布门禁。报告中任何声明为 target 或 broken 的工具仍会被视为错误，并且回归测试会固定其确切状态。当前基线中没有 target 或 broken 实现，也没有实现偏差，因此，任何离开 asBuilt 的实现、任何结构性契约错误或任何可选输入覆盖偏差，都会阻止合并和发布。--structural-strict 仍仅可用于本地分阶段修复工作。

此门禁可验证操作标识、顶层 MCP 字段归属、必需的 Apple 输入、类型化内部值，以及响应来源和指针的溯源关系。完整的 MCP 类型、枚举和范围一致性，以及完整的类型化响应架构，仍属于独立的优化阶段；映射状态并不代表已获得 Apple 账户权限，也不代表已在现实场景中成功验收。

较早的 openapi-coverage 命令仍可用于生成高层领域报告，见 ASC-OPENAPI-COVERAGE-GENERATED.md。操作契约是权威的发布门禁。

可用的工作器名称：

工具目录规模

当 MCP 客户端预先加载每个工具定义时，架构的大致占用量为：

**工具数最多的工作器：**订阅（99 个工具）、App 内购买（59 个工具）、Xcode Cloud（42 个工具）、屏幕截图（19 个工具）、配置文件（17 个工具）。

具体开销取决于 MCP 宿主的序列化方式、分词器和工具发现策略。现代客户端可能会等到需要时才加载架构。如果客户端设有工具数量限制，或者你希望使用更小、更聚焦的目录，请使用 --workers。

可用工具

514 个工具分布在 34 个 App Store 工具领域和 2 个核心领域（使用 36 个 --workers 过滤键，参见工作器过滤）：

使用示例

完整发布工作流

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 分发

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: [...])

审核管理

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

多公司工作流

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 限制

架构

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

设计原则

• Swift 6 严格并发 — 所有工作器和服务都符合 Sendable，并正确隔离 Actor
• 基于 Actor 的 HTTP 客户端 — 具备线程安全、指数退避和重试逻辑
• 基于前缀的路由 — WorkerManager 按名称前缀路由工具调用（无需配置）
• 最少依赖 — 仅依赖 MCP Swift SDK

故障排查

获取帮助

提交报告前，请先搜索现有问题。如果问题是新出现的，请提交问题，并附上：

• macOS 版本和安装方式；
• MCP 客户端名称和版本；
• 所选的 --workers 值（如有）；
• 准确的错误消息和最精简的可复现请求。

发布日志前，请删除 Key ID、Issuer ID、私钥、签名 URL、令牌和账户数据。请按照 SECURITY.md 中的说明私下报告安全漏洞。代码贡献请参阅 CONTRIBUTING.md。

开发

构建

swift build              # Debug build
swift build -c release   # Release build (optimized)
swift package clean      # Clean build artifacts

测试模式

.build/debug/asc-mcp --test    # Runs built-in integration tests

添加新工具

1. 在相应的 Worker+Handlers.swift 中创建处理程序方法
2. 在 Worker+ToolDefinitions.swift 中添加工具定义
3. 在工作器的 getTools() 方法中注册
4. 在工作器的 handleTool() 开关中添加路由分支
5. WorkerManager 会根据前缀自动路由，无需在此处更改

添加新工作器

1. 创建目录：Workers/MyWorker/
2. 创建 3 个文件：MyWorker.swift、MyWorker+ToolDefinitions.swift、MyWorker+Handlers.swift
3. 在 WorkerManager.swift 中添加工作器属性并进行初始化
4. 在 WorkerManager.registerWorkers() 中添加路由规则
5. 添加 getMyTools() 辅助方法

贡献

欢迎贡献！详情请参阅贡献指南。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

致谢

• Model Context Protocol — 协议规范和 Swift SDK
• App Store Connect API — Apple 官方 REST API

_{这是一款由社区维护的非官方工具，与 Apple Inc. 无关，也未获得其认可。}