app-store-connect-mcp

app-store-connect-mcp

Apple App Store Connect API 的完整 Model Context Protocol（MCP）服务。 1316 个工具，覆盖率达 100%，涵盖 Apple 官方 OpenAPI 规范中所有未弃用的操作——TestFlight、Xcode Cloud、Game Center、App Clips、应用内购买、订阅、审核提交、分析、配置，以及 Apple 提供的其他所有功能。可与 Claude、Cursor、VS Code Copilot、Codex CLI、Gemini CLI、Windsurf 或任何 MCP 客户端配合使用。

另请参阅： google-play-developer-mcp——为 Google Play Console 实现相同理念的 MCP 服务。

---

目录

• 项目缘由
• 功能矩阵
• 快速开始
• 分步设置
• 在 MCP 客户端中注册
• 使用示例
• 从 asc-mcp (zelentsov-dev) 迁移
• 安全性
• 设计说明
• 参与贡献
• 版本历史
• 参考资料

---

项目缘由

App Store Connect 的功能非常庞大。Apple 自己的 OpenAPI 规范目前列出了 1303 个操作，涵盖 203 个资源组——TestFlight、Xcode Cloud、Game Center、App Clips、应用内购买、订阅、优惠代码、审核提交、替代分发（EU DMA）、分析、指标、隐私清单、配置、用户……还有更多。

每个社区 MCP 服务都只覆盖其中一部分，没有一个能涵盖全部内容。

app-store-connect-mcp 可以做到。

属性	本服务	典型的社区 MCP 服务
App Store Connect API 覆盖范围	✅ 1300+ 个工具（覆盖规范 v4.5.1 的 100%）	部分覆盖（通常为 50–150 个工具）
Xcode Cloud	✅ 所有 ciProducts / ciWorkflows / ciBuildRuns / ciBuildActions / ciArtifacts / ciIssues / ciTestResults	❌
Game Center	✅ 成就、排行榜、群组、匹配、词汇表	❌
App Clips	✅ 默认体验和高级体验、审核详情、页眉图像	❌
Review Submissions v2	✅	通常仍使用旧版 appStoreVersionSubmissions
替代分发（EU DMA）	✅	❌
App 数据使用情况（隐私）	✅	❌
多账户（在开发者账户之间切换）	✅ 本地注册表 + 按项目设置的 ASC_ACCOUNT 固定账户	通常仅支持一个账户
凭证安全	仓库中不包含 .p8 内容、进程缓存中不保存密钥、严格的 .gitignore	因实现而异
由规范驱动——规范更新时自动重新生成	✅ npm run codegen	❌

如果你使用 AI 助手管理 App Store Connect——自动化提交、管理 TestFlight、管理 IAP / 订阅目录、审核分流、分析或编排 Xcode Cloud——只需安装一次，就能为助手提供完整工具箱。

---

功能矩阵

共 1316 个工具（截至规范 v4.5.1）：

• 6 个 accounts_*——本地多账户注册表（添加 / 列出 / 切换 / 移除 / 更新 / 当前账户）
• 2 个 auth_*——auth_status（就绪状态）和 auth_revoke_cache
• 根据官方 App Store Connect OpenAPI 规范自动生成的 1303 个工具，每个操作对应一个，涵盖所有资源组：
  • Apps / App Infos / App Store Versions / App Store Version Localizations / Phased Releases / Version Submissions
  • Review Submissions（v2）+ Review Submission Items + App Store Review Attachments + App Store Review Details
  • TestFlight：Beta Groups、Beta Testers、Beta App Review Details/Submissions、Beta App Localizations、Beta Build Localizations、Beta License Agreements、Beta Feedback Screenshot/Crash Submissions、Beta Invitees、Builds、Build Bundles、Build Bundle File Sizes
  • Xcode Cloud：Ci Products、Ci Workflows、Ci Build Runs、Ci Build Actions、Ci Artifacts、Ci Issues、Ci Test Results、Ci Xcode Versions、Ci Mac Os Versions、Ci Scm Repositories / References / Pull Requests / Providers
  • Game Center：Achievements、Leaderboards、Leaderboard Sets、Groups、Matchmaking Queues / Rule Sets / Rules / Teams、Activities、Player Scores / Achievements、App Versions、Enabled Versions、Details、Vocabularies，以及所有 Localizations / Images / Releases
  • App Clips：App Clips、Default / Advanced Experiences、Default / Advanced Experience Localizations、Header Images、Advanced Experience Images、App Store Review Details
  • In-App Purchases：IAP v2、Subscriptions、Subscription Groups、Subscription Offer Codes（custom + one-time-use）、Subscription Prices、Subscription Promotional Offers、Subscription Introductory Offers、Subscription Availabilities、Win-back Offers、Promoted Purchases
  • Pricing & Availability：App Prices、App Price Points、App Price Schedules、App Availabilities V2、Territories、Territory Availabilities
  • Custom Product Pages + PPO（A/B 测试）：App Custom Product Pages、Versions、Localizations、App Store Version Experiments V2 + Treatments + Localizations
  • Screenshots & Previews：App Screenshots、App Screenshot Sets、App Previews、App Preview Sets、App Event Screenshots、App Event Video Clips
  • Provisioning：Bundle Ids、Bundle Id Capabilities、Certificates、Devices、Profiles、Pass Type Ids
  • Users & Access：Users、User Invitations、Actors、Sandbox Testers
  • Encryption / Compliance：App Encryption Declarations + Documents、Age Rating Declarations、App Data Usages + Categories + Purposes + Data Protections + Publish State、Accessibility Declarations、End User License Agreements
  • Alternative Distribution（EU DMA）：Alternative Distribution Keys、Domains、Packages、Package Versions / Variants / Deltas、Marketplace Search Details、Marketplace Webhooks
  • Analytics：Analytics Reports、Report Requests、Report Instances、Report Segments、Diagnostic Signatures
  • Metrics：App Perf、Build Perf、Power Perf、Diagnostic Logs
  • Sales & Finance：Sales Reports、Finance Reports
  • Reviews：Customer Reviews、Customer Review Responses
  • Routing App Coverages、App Categories、App Events + Localizations、Android ↔ iOS App Mapping、External Purchase Collectors…
  • 规范 4.5 新增内容：App Asset Libraries（images、videos、placements）、带有 V2 本地化内容和图片的 In-App Purchase / Subscription / Subscription Group Versions、Subscription Plan Availabilities、Game Center Score Moderations and Blocked Players、App Performance Overviews
• 手写的 5 个辅助工具，用于无法简单映射到单个操作的工作流：
  • asset_upload_file——三步资源上传协议的第 2 步（screenshots、previews、review attachments、IAP review screenshots、App Clip header images、Game Center images、routing app coverages）
  • sales_reports_download——下载并解压销售报告，返回解析后的 TSV
  • finance_reports_download——同样用于财务报告
  • analytics_report_instance_wait——轮询，直到报告状态为 COMPLETED/FAILED
  • ci_build_run_wait——轮询 Xcode Cloud 构建运行，直到完成 运行 auth_status，然后运行 apps_get_collection，验证端到端流程。

---

快速开始

从 npm 安装：

npm install -g apple-app-store-connect-mcp

或者无需安装，直接运行：

npx -y apple-app-store-connect-mcp

关于包名。 npm 上的包名是 apple-app-store-connect-mcp。安装后，$PATH 上的命令是 app-store-connect-mcp（即 bin 名称）——下面的 MCP 客户端配置指向的就是它。

然后添加到 MCP 客户端配置中（示例：Claude Code）：

{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp"
    }
  }
}

最后，注册你的 App Store Connect API 密钥（详情见下文）：

accounts_add
  name: my-app
  keyId: AB12CD34EF
  issuerId: 69a6de70-...
  keyFile: /Users/you/.config/app-store-connect-mcp/AuthKey_AB12CD34EF.p8

---

分步设置

1. 创建 App Store Connect API 密钥

1. 打开 App Store Connect。
2. 用户与访问 → 集成 → App Store Connect API。
3. 点击 生成 API 密钥（需要账户持有人或管理员角色）。
4. 为密钥命名，选择所需的访问级别（管理员、开发者、财务、营销等），然后点击 生成。
5. 复制 Key ID 和 Issuer ID（显示在页面顶部）。
6. 点击 下载 API 密钥。这会生成一个 AuthKey_<KEYID>.p8 文件。**此密钥只能下载一次。**请将它保存在所有 git 仓库之外，例如保存到 ~/.config/app-store-connect-mcp/AuthKey_AB12CD34EF.p8，并设置 chmod 600。

2. 向此 MCP 服务注册密钥

启动已配置此服务的任意 MCP 客户端，然后调用：

accounts_add
  name: my-app
  keyId: <the 10-char Key ID>
  issuerId: <the UUID shown above the API keys list>
  keyFile: /absolute/path/to/AuthKey_XXXXXXXXXX.p8
  description: (optional)

3. 验证

auth_status

应返回 { source: "accounts", tokenAcquired: true, expiresAt: ... }。

apps_get_collection

列出该密钥可以访问的 App。

4. 管理多个账户

accounts_add    name: client-a  keyId: ... issuerId: ... keyFile: ...
accounts_add    name: client-b  keyId: ... issuerId: ... keyFile: ...
accounts_switch name: client-b
accounts_list

之后的所有调用都会针对当前切换到的账户。

5. 为每个项目固定一个账户（ASC_ACCOUNT）

currentAccount 是 accounts.json 中的单个全局值，由这台机器上的所有 MCP 客户端共享。如果你需要处理多个 App Store Connect 账户，这可能会造成严重问题：一个项目中的 accounts_switch 会在不知情的情况下切换其他所有项目的账户，而项目 A 中的助手可能会因此向账户 B 的 App 写入数据。

请为每个服务进程固定账户。在 MCP 客户端配置中设置 ASC_ACCOUNT：

{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp",
      "env": { "ASC_ACCOUNT": "acme-app" }
    }
  }
}

固定账户后：

• 无论 currentAccount 当前是什么值，每次调用都会使用该账户。
• 切换到任何其他账户时，accounts_switch 都会明确报错，而不会在不知情的情况下切换目标账户。
• accounts_remove 会拒绝删除固定的账户。
• auth_status 和 accounts_current 会报告 pinnedTo，因此始终可以看到会话使用的是哪个账户。

如果 ASC_ACCOUNT 指定的账户尚未注册，调用会明确报错，而不会回退到其他账户。

为每个项目分别固定账户，这样各项目就完全不依赖共享的全局值。

环境变量兼容模式

为兼容旧版设置（例如 zelentsov-dev/asc-mcp），此服务也接受：

ASC_KEY_ID="..."
ASC_ISSUER_ID="..."
ASC_PRIVATE_KEY_PATH="/absolute/path/to/AuthKey_XXX.p8"

如果没有通过 accounts_add 注册账户，服务会回退到这些环境变量。accounts_* 工具始终具有更高优先级。

---

在 MCP 客户端中注册

Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp"
    }
  }
}

Claude Code

claude mcp add app-store-connect app-store-connect-mcp

也可以编辑 ~/.claude.json：

{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp"
    }
  }
}

如果你需要处理多个 App Store Connect 账户，请改为在每个项目的 .mcp.json 中添加此服务并固定账户——参见为每个项目固定一个账户：

{
  "mcpServers": {
    "app-store-connect": {
      "command": "app-store-connect-mcp",
      "env": { "ASC_ACCOUNT": "acme-app" }
    }
  }
}

Cursor

设置 → MCP → 添加新的 MCP 服务：

{
  "app-store-connect": {
    "command": "app-store-connect-mcp"
  }
}

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "app-store-connect": {
      "type": "stdio",
      "command": "app-store-connect-mcp"
    }
  }
}

Codex CLI / Gemini CLI / Windsurf / Continue

任何符合 MCP 规范的客户端都接受相同的 command 条目——将其指向全局安装的 app-store-connect-mcp 二进制文件；如果从源代码运行，则指向 node /path/to/dist/index.js。

从源代码运行（不进行全局安装）

git clone https://github.com/devinwang/app-store-connect-mcp.git
cd app-store-connect-mcp
npm install
npm run build

然后在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "app-store-connect": {
      "command": "node",
      "args": ["/absolute/path/to/app-store-connect-mcp/dist/index.js"]
    }
  }
}

---

使用示例

查看密钥可以访问哪些 App

accounts_switch name: my-app
auth_status
apps_get_collection

按版本号和 buildNumber 获取构建并提交到 TestFlight

builds_get_collection
  "filter[preReleaseVersion.version]": "1.2.0"
  "filter[version]": "147"

beta_groups_get_collection
  "filter[app]": <APP_ID>
  "fields[betaGroups]": "name,publicLinkEnabled"

builds_beta_groups_create_to_many_relationship
  id: <BUILD_ID>
  body:
    data:
      - type: betaGroups
        id: <BETA_GROUP_ID>

builds_update_instance
  id: <BUILD_ID>
  body:
    data:
      type: builds
      id: <BUILD_ID>
      attributes:
        expired: false

上传屏幕截图（3 步资源流程）

app_screenshots_create_instance
  body:
    data:
      type: appScreenshots
      attributes:
        fileName: "en-US-iphone-6_9-1.png"
        fileSize: 2415122
      relationships:
        appScreenshotSet:
          data: { type: appScreenshotSets, id: <SET_ID> }
# → response includes the new `data.id` (asset is now AWAITING_UPLOAD)

asset_upload_file
  filePath: /abs/path/to/screenshot.png
  assetType: appScreenshots     # preferred: tool fetches uploadOperations
  assetId: <SCREENSHOT_ID>      #           server-side (signature stays server-side)
# (legacy: pass `uploadOperations: [...]` from the create response instead)

app_screenshots_update_instance
  id: <SCREENSHOT_ID>
  body:
    data:
      type: appScreenshots
      id: <SCREENSHOT_ID>
      attributes:
        uploaded: true
        sourceFileChecksum: <MD5>

触发 Xcode Cloud 构建并等待完成

ci_build_runs_create_instance
  body:
    data:
      type: ciBuildRuns
      relationships:
        workflow:
          data: { type: ciWorkflows, id: <WORKFLOW_ID> }
# → response includes `data.id`

ci_build_run_wait
  id: <BUILD_RUN_ID>
  timeoutMs: 3600000

回复客户评价

customer_reviews_get_collection
  "filter[app]": <APP_ID>
  "sort": "-createdDate"
  "limit": 10

customer_review_responses_v1_create_instance
  body:
    data:
      type: customerReviewResponses
      attributes:
        responseBody: "Thanks for the feedback — we fixed this crash in 1.2.1. Please give it another try!"
      relationships:
        review:
          data: { type: customerReviews, id: <REVIEW_ID> }

获取销售报告（一天）

sales_reports_download
  "filter[frequency]": DAILY
  "filter[reportType]": SALES
  "filter[reportSubType]": SUMMARY
  "filter[vendorNumber]": "12345678"
  "filter[reportDate]": "2026-04-20"

返回解析后的行。添加 parse: false 可获取原始 TSV。

创建并激活订阅

subscription_groups_create_instance
  body: { data: { type: subscriptionGroups, attributes: { referenceName: "Premium" }, relationships: { app: { data: { type: apps, id: <APP_ID> } } } } }

subscriptions_create_instance
  body: { data: { type: subscriptions, attributes: { productId: "com.example.premium.monthly", name: "Premium Monthly", subscriptionPeriod: "ONE_MONTH" }, relationships: { group: { data: { type: subscriptionGroups, id: <GROUP_ID> } } } } }

subscription_prices_create_instance
  body: { data: { type: subscriptionPrices, relationships: { subscription: { data: { type: subscriptions, id: <SUB_ID> } }, territory: { data: { type: territories, id: "USA" } }, subscriptionPricePoint: { data: { type: subscriptionPricePoints, id: <PRICE_POINT_ID> } } } } }

---

从 asc-mcp (zelentsov-dev) 迁移

此服务替代 github.com/zelentsov-dev/asc-mcp。主要区别：

• 范围。 该服务实现了约 90 个工具；本服务实现了规范中的全部 1303 个操作，外加辅助工具。
• 工具名称。 zelentsov-dev/asc-mcp 使用简化名称，例如 apps_search、reviews_list、app_versions_submit_for_review。本服务使用 Apple 的官方 operationId 蛇形命名形式，例如 apps_get_collection、customer_reviews_get_collection、review_submissions_create_instance。没有自动转换功能：请更新任何依赖旧名称的提示词或脚本。
• 凭据兼容性。 相同的环境变量（ASC_KEY_ID、ASC_ISSUER_ID、ASC_PRIVATE_KEY_PATH）仍然有效，因此迁移时无需移动 .p8 文件。你会收到一次 stderr 警告，建议通过 accounts_add 注册以支持多个账户。
• company_* → accounts_*。 调整认知模型：旧服务中的“company”在这里称为“account”。

完整的逐名称映射见 docs/MIGRATION.md。

---

安全

此仓库不包含任何凭据。你需要提供 App Store Connect API .p8 文件；服务仅记录其路径。

磁盘上存储的内容

位置	内容
~/.app-store-connect-mcp/accounts.json	账户名称、密钥 ID、签发者 ID、密钥文件路径、描述。不含机密信息。文件权限为 0600，目录权限为 0700。
你放置 AuthKey_*.p8 的位置	实际私钥。绝不会提交到代码库。绝不会在一次 JWT 签名操作之外将其复制到服务内存中。
仓库内容	仅包含代码。不含夹具、示例密钥或真实密钥 ID。

内存中的内容

时间	内容
JWT 签名时	使用 readFileSync 读取 .p8 内容，传递给 jwt.sign，之后立即对缓冲区调用 fill(0) 并解除引用。
调用之间	有效期为 20 分钟的已签名 JWT 缓存在 token-cache.ts 的局部变量中。它仅存于内存，不会持久化到磁盘。调用 accounts_switch、accounts_update、accounts_remove 和 auth_revoke_cache 时会将其丢弃。
工具输出中	所有内容在输出前都会经过 redact() 处理。类似 JWT 的字符串、PEM 块、Bearer 令牌和较长的十六进制令牌都会被替换为 [REDACTED …]，以纵深防御的方式防止任何代码路径意外记录这些内容。

.gitignore 屏蔽项

• *.p8、AuthKey_*、AuthKey_*.p8
• *.pem、*.p12、*.pfx、*.key、id_rsa*
• accounts.json、.app-store-connect-mcp/
• credentials/、keys/、secrets/
• .env、.env.*（保留 .env.example）

安全建议

• 将 .p8 文件保存在计算机上所有 git 仓库之外。
• 为 API 密钥分配工作流所需的最小权限。Admin 权限允许此 MCP 执行任何操作，包括删除商店元数据。请按需限制权限。
• 定期轮换密钥：在 App Store Connect → Users and Access → Integrations 中撤销旧密钥，生成新密钥，然后运行 accounts_update --keyFile <newPath>。
• auth_status 仅返回密钥 ID、签发者 ID、一个布尔值和 JWT 到期时间戳。它绝不会返回 JWT 或 .p8 内容。
• 此仓库中的 CI 工作流会在 dist/ 中检测到任何私钥材料正则匹配项时使构建失败。

审计跟踪

Apple 会记录使用你的密钥 ID 发出的每次 API 调用。如果你怀疑密钥遭到滥用，请打开 App Store Connect → Users and Access → Integrations 并撤销该密钥；使用该密钥签名的任何未过期 JWT 都会立即失效。

---

设计说明

• 规范驱动。 1316 个工具中有 1303 个是根据 Apple 官方 OpenAPI 规范（spec/app-store-connect-openapi.json）自动生成的。Apple 发布新版本后，只需运行 npm run spec:download && npm run codegen && npm run build 即可完成更新。
• 名称与 operationId 一一对应。 工具名称是将 Apple 的 operationId 转换为 snake_case 得到的。因此，MCP 工具名称与官方 REST 参考文档一致，大模型阅读 Apple 文档时，无需转换即可选择正确的工具。
• 实用的输入验证。 路径参数是必填的、经过类型定义的 zod 字符串；查询参数是可选的、经过类型定义的 zod 字段，并使用 Apple 的精确方括号名称（filter[name]、fields[apps]、limit[appStoreVersions]）。请求正文使用 z.record(z.unknown())，其描述指向 OpenAPI 组件架构；ASC 会在服务端验证请求正文，我们的错误转换器会清晰地指出错误。为每个 JSON:API 信封生成完整的 zod 树会使服务体积膨胀 10 倍，价值却微乎其微。
• 错误转换。 401 转换为“JWT 被拒绝——请轮换密钥或检查时钟偏差”，403 转换为“密钥未获授权使用此端点”，422 会显示 ASC 响应中的确切 source.pointer，429 会说明每个团队的配额，5xx 会指向 https://developer.apple.com/system-status/。
• 无状态传输。 仅使用 stdio。没有网络监听器，除账户文件外不保留任何持久状态。
• 零遥测。 服务绝不会向外发送数据。

---

参与贡献

欢迎提交 PR。提交之前请确认：

• 在 Node 18 / 20 / 22 上，npm run typecheck 和 npm run build 均能通过（CI 也会运行这些检查）。
• 在 issue、PR、fixture 或示例中，绝不要包含真实的 .p8、真实的 keyId、真实的 issuerId 或真实的 JWT。
• 更新至新版 OpenAPI 规范时：
  1. npm run spec:download
  2. npm run codegen — 重新生成 src/tools/generated/ 和 spec/coverage-report.txt
  3. npm run build
  4. 简要检查 spec/coverage-report.txt 的差异——工具数量变化 10 个或以上，或新增顶级标签时，应在 CHANGELOG 中注明。
• 手动编写的新工具放在 src/tools/overrides.ts 中，其名称不得与任何生成的名称冲突。

---

版本历史

0.1.0 — 2026-04-21（首次公开发布）

• 1221 个 MCP 工具： 6 个账户工具、2 个认证工具、根据 Apple App Store Connect OpenAPI 规范 v4.3 自动生成的 1208 个工具，以及 5 个手动编写的辅助工具（资源上传、销售／财务报告下载、轮询）。
• 100% 规范覆盖率——规范中每个未弃用的操作都有对应工具，已弃用的操作仍会以 [DEPRECATED] 前缀提供。
• 仓库中不含凭据。 严格的 .gitignore 规则、.p8 内容不会缓存在进程内存中、仅使用内存缓存 JWT、全面脱敏输出。
• 通过 ~/.app-store-connect-mcp/accounts.json 支持多账户（仅存储路径）。
• 提供对 ASC_KEY_ID / ASC_ISSUER_ID / ASC_PRIVATE_KEY_PATH 环境变量的兼容模式（可直接替换 zelentsov-dev/asc-mcp 配置）。
• 通过 npm run codegen 根据规范重新生成。
• 针对 ASC 所有常见故障模式提供错误转换。

---

参考资料

• App Store Connect API — 文档主页
• App Store Connect API — REST 参考
• App Store Connect OpenAPI 规范（ZIP）
• 创建 API 密钥以授权 API 请求
• 为 API 请求生成令牌（JWT 格式）
• 模型上下文协议规范
• Anthropic Claude — MCP 文档

---

License

MIT — see LICENSE.