appstore-release-mcp

appstore-release-mcp

一个 MCP 服务，可驱动 iOS 和 macOS 应用的完整 App Store 发布周期：提升版本号 → 归档并上传到 TestFlight → 元数据 → 提交审核 → 查看状态。

**它的不同之处：**现有的 App Store Connect MCP 服务都只是封装 REST API——处理元数据、TestFlight 管理和分析。它们都无法完成 REST API 不支持的那一步：将二进制文件上传到 Apple 的服务器。此服务是一个发布助手，而非 API 浏览器，并提供两种上传方式：

• 直接调用 ASC REST API（ES256 JWT，通过 node:crypto 实现零依赖签名），用于查看状态、构建版本、管理元数据和提交审核
• asc_upload_build——使用你现有的 fastlane lane 进行归档、签名和上传，并作为异步作业运行，同时支持轮询日志（实际归档需要 5–15 分钟，没有任何 MCP 超时设置能一直等待）
• asc_upload_ipa——已经有签名的 .ipa？（来自 eas build、CI 流水线或手动 Xcode 归档）可通过 xcrun altool 直接上传——无需 fastlane，无需本地归档步骤，除你已有的 ASC API 密钥外无需进行其他配置
• 在本地项目文件中提升版本号，支持 project.pbxproj（以及 xcodegen 项目的 project.yml）

要求

• 安装了 Xcode 命令行工具的 macOS（asc_upload_ipa 使用 xcrun altool）
• fastlane，并包含用于构建和上传的 lane（例如 beta）——仅 asc_upload_build 需要；如果只使用 asc_upload_ipa，可完全跳过
• App Store Connect API 密钥（.p8）

设置

1. 生成 ASC API 密钥（仅需一次）：前往 App Store Connect → Users and Access → Integrations → App Store Connect API → Team Keys → Generate（角色：App Manager）。下载 .p8 文件——Apple 只允许下载一次。将其保存在 ~/.appstoreconnect/private_keys/ 中。

2. 在 Claude Code 中注册：

claude mcp add appstore \
  -e APPLE_KEY_ID=XXXXXXXXXX \
  -e APPLE_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e ASC_KEY_PATH=$HOME/.appstoreconnect/private_keys/AuthKey_XXXXXXXXXX.p8 \
  -e APPLE_TEAM_ID=XXXXXXXXXX \
  -e ASC_BUNDLE_ID=com.example.myapp \
  -e ASC_PROJECT_DIR=/path/to/your/xcode/project \
  -- npx appstore-release-mcp

对于 Fastfile 使用 platform :mac 的 macOS 应用，请添加 -e ASC_PLATFORM=MAC_OS -e ASC_FASTLANE_PLATFORM=mac。

3. **验证：**让 Agent 运行 asc_doctor。所有检查都应显示 ✓。

工具

工具	功能
asc_doctor	验证配置、凭据、fastlane/xcodebuild/altool 和应用记录——首先运行
asc_app_status	一次调用即可查看版本、审核状态和近期构建版本
asc_list_builds	查看构建处理状态（上传后等待状态变为 VALID）
asc_bump_version	提升构建号／设置本地项目文件中的营销版本号
asc_upload_build	将你的 fastlane 上传 lane 作为异步作业运行——立即返回作业 ID
asc_upload_ipa	通过 xcrun altool 上传已构建的 .ipa——异步作业，无需 fastlane
asc_job_status	轮询由 asc_upload_build 或 asc_upload_ipa 启动的作业；查看状态和日志末尾
asc_update_metadata	通过 REST 更新描述、关键词、更新内容和推广文本
asc_submit_review	附加构建版本、创建审核提交并提交

发布演练

使用 fastlane 在本地构建：

asc_doctor                                   # toolchain healthy?
asc_bump_version {marketing_version: "1.1.0"}
asc_upload_build                             # → job id
asc_job_status {job_id}                      # poll until succeeded
asc_list_builds                              # wait for processingState VALID
asc_update_metadata {whats_new: "...", create_version: "1.1.0"}
asc_submit_review {build_id}                 # point of no return
asc_app_status                               # WAITING_FOR_REVIEW

已经有签名的 .ipa（EAS Build、CI、手动归档）——无需 fastlane：

asc_doctor
asc_upload_ipa {ipa_path: "./build/app.ipa"} # → job id
asc_job_status {job_id}                      # poll until succeeded
asc_list_builds                              # wait for processingState VALID
asc_update_metadata {whats_new: "...", create_version: "1.1.0"}
asc_submit_review {build_id}
asc_app_status

环境变量

凭据名称有意与 fastlane 的 app_store_connect_api_key 保持一致，因此一套凭据即可同时用于两者。

变量	必需	说明
APPLE_KEY_ID	是	ASC API 密钥 ID
APPLE_ISSUER_ID	是	ASC 颁发者 ID
APPLE_KEY_CONTENT / ASC_KEY_PATH	二选一	base64 编码的 .p8 文件／.p8 文件路径
APPLE_TEAM_ID	asc_upload_build 必需	Apple Developer 团队 ID（asc_upload_ipa 不需要）
ASC_BUNDLE_ID	是	应用的 bundle 标识符
ASC_PROJECT_DIR	建议设置	fastlane 运行所在的 Xcode 项目根目录（默认：当前工作目录）
ASC_PLATFORM	否	IOS（默认）、MAC_OS、TV_OS、VISION_OS
ASC_FASTLANE_LANE	否	上传 lane 名称（默认：beta）
ASC_FASTLANE_PLATFORM	否	fastlane 平台前缀，例如 mac 或 ios
ASC_UPLOAD_CMD	否	完整覆盖命令，例如 bundle exec fastlane ios beta

注意事项

• 构建任务是服务进程的子进程；如果 MCP 客户端在构建过程中断开连接，任务就会终止。无论如何，日志都会保留在 ~/.appstore-mcp/jobs/ 中。
• asc_submit_review 是发布流程中不可逆的步骤——工具说明会要求 Agent 先与人类确认。

许可证

MIT