App Store Connect

appstore-mcp

一个用 Rust 编写的 MCP 服务，可向 AI Agent 提供 Apple App Store Connect API。它涵盖完整的产品生命周期，包括 App 和元数据、App 内购买项目、订阅及其优惠、定价和可用性、App Store 版本、App Review 提交、TestFlight、配置描述文件和签名、资源上传、推广购买、客户评论、分阶段发布、用户和访问权限、App 内活动、Xcode Cloud 以及分析报告，共提供 114 个工具；还可以通过两个通用 JSON:API 工具访问其他任意 App Store Connect 端点。

基于官方 rmcp SDK，通过 stdio 运行。

📖 完整工具参考 → docs/TOOLS.md — 介绍每个工具的用途和参数。

每个工具都带有 MCP 注释，因此客户端可以区分 list_apps 和 remove_user。你可以只提供所需领域的工具（ASC_TOOLS），也可以只提供无法写入数据的工具（ASC_READ_ONLY）——请参阅选择要提供的工具。

设计：混合覆盖

App Store Connect API 有数百个端点，但它们统一采用 JSON:API。本服务没有为每个端点都提供一个工具，而是采用混合模式：

• 精选工具（112 个），用于常见、多步骤或容易出错的工作流——App 和元数据、IAP、订阅和优惠、版本、定价、可用性、App Review 提交、TestFlight、配置描述文件、资源上传、推广购买、客户评论、分阶段发布、用户、App 内活动、Xcode Cloud、分析报告和自定产品页面。
• 两个通用的兜底工具——appstore_request 和 appstore_list——可以通过原始 JSON:API 文档调用任意端点。

工具

分组	工具
通用	appstore_request、appstore_list
App 和元数据	list_apps、get_app、update_app、list_app_infos、update_app_info、set_age_rating、create_app_info_localization、update_app_info_localization
App 内购买项目（v2）	list_in_app_purchases、create_in_app_purchase、update_in_app_purchase、delete_in_app_purchase、create_iap_localization、set_iap_price_schedule、upload_iap_review_screenshot
订阅	list_subscription_groups、create_subscription_group、create_subscription、update_subscription、create_subscription_localization、set_subscription_price
版本和元数据	list_app_store_versions、create_app_store_version、create_version_localization、update_version_localization
App 审核提交	create_review_submission、add_review_submission_item、submit_review_submission、list_review_submissions、submit_in_app_purchase、set_app_review_detail、create_app_encryption_declaration、assign_build_encryption_declaration
定价	list_territories、list_iap_price_points、list_subscription_price_points
可用性	set_iap_availability、set_subscription_availability、set_app_availability
TestFlight	list_builds、list_beta_groups、create_beta_group、add_beta_tester、submit_build_for_beta_review、set_build_test_notes、set_build_beta_detail、set_beta_app_review_detail、expire_build、add_build_to_beta_group
配置和签名	list_bundle_ids、create_bundle_id、enable_bundle_id_capability、disable_bundle_id_capability、list_certificates、create_certificate、list_devices、register_device、list_profiles、create_profile
资源	upload_app_screenshot、upload_app_preview、create_screenshot_set、create_preview_set、delete_screenshot_set、delete_preview_set、reorder_screenshots
订阅优惠	create_introductory_offer、create_promotional_offer、create_winback_offer、list_winback_offers
优惠码	create_offer_code、generate_one_time_use_codes、create_custom_offer_code、list_offer_codes
推广购买项目	create_promoted_purchase、update_promoted_purchase、set_promoted_purchase_order、list_promoted_purchases
客户评价	list_customer_reviews、respond_to_review、delete_review_response
分阶段发布	start_phased_release、update_phased_release
用户和访问权限	list_users、invite_user、update_user、remove_user
App 内活动	create_app_event、create_app_event_localization、upload_app_event_screenshot
Xcode Cloud	list_ci_products、list_ci_workflows、start_ci_build、get_ci_build_run、list_ci_build_actions
分析报告	request_analytics_report、list_analytics_reports、list_analytics_report_instances、list_analytics_report_segments、download_analytics_segment
自定产品页面	list_custom_product_pages、get_custom_product_page、create_custom_product_page、update_custom_product_page、delete_custom_product_page、list_custom_product_page_versions、create_custom_product_page_version、list_custom_product_page_localizations、create_custom_product_page_localization、update_custom_product_page_localization、create_cpp_screenshot_set、create_cpp_preview_set

每个工具的说明和参数请参阅 docs/TOOLS.md。自定产品页面的图片可使用现有的 upload_app_screenshot / upload_app_preview 工具上传。

安装

每个 GitHub Release 均附有适用于 macOS（通用版）、Linux（x86-64）和 Windows（x86-64） 的预编译二进制文件。 请选择与客户端对应的渠道；所有渠道都需要凭据（参见凭据）。

Claude Desktop — 一键安装包

从最新版本下载 appstore-mcp.mcpb，并使用 Claude Desktop 打开 （Settings → Extensions → Install Extension…，或将文件拖到窗口中）。 系统会提示你提供 Issuer ID、Key ID 和 .p8 密钥文件。安装包包含三个平台的二进制文件，并会自动选择合适的文件。

Claude Code — 插件市场

/plugin marketplace add forgeopslabs/appstore-mcp
/plugin install appstore-mcp@forgeopslabs

插件会从你的 PATH 启动 appstore-mcp 二进制文件，因此请先安装它—— 从最新版本下载适用于你操作系统的二进制文件 并将其放入 PATH，或者运行 cargo install --git https://github.com/forgeopslabs/appstore-mcp。 在启动 Claude Code 的环境中设置 ASC_ISSUER_ID、ASC_KEY_ID 和 ASC_PRIVATE_KEY_PATH。

Codex

Codex 直接配置 MCP 服务（无需市场）。确保 appstore-mcp 位于你的 PATH 中：

codex mcp add appstore \
  --env ASC_ISSUER_ID=... --env ASC_KEY_ID=... \
  --env ASC_PRIVATE_KEY_PATH=/path/AuthKey_XXXXXX.p8 \
  -- appstore-mcp

或在 ~/.codex/config.toml 中配置：

[mcp_servers.appstore]
command = "appstore-mcp"
args = []
env = { ASC_ISSUER_ID = "...", ASC_KEY_ID = "...", ASC_PRIVATE_KEY_PATH = "/path/AuthKey_XXXXXX.p8" }

MCP Registry

已发布为 io.github.forgeopslabs/appstore-mcp（元数据位于 server.json），任何兼容 MCP 的客户端都可以发现它。

从源代码构建

cargo build --release    # -> target/release/appstore-mcp

凭据

在 App Store Connect → Users and Access → Integrations → App Store Connect API 中生成 Team Key，并下载 .p8 文件。然后设置：

变量	必需	说明
ASC_ISSUER_ID	✅	显示在密钥表格上方的 Issuer UUID。
ASC_KEY_ID	✅	API 密钥的 Key ID。
ASC_PRIVATE_KEY	二选一	内联 .p8 PEM 内容。
ASC_PRIVATE_KEY_PATH	二选一	已下载的 .p8 文件路径。
ASC_BASE_URL	可选	覆盖 API 源地址。
ASC_LOG	可选	日志筛选级别（输出到 stderr）。默认值为 info。

请参阅 .env.example。服务端会使用你的密钥签名一个 短时有效的 ES256 JWT 来验证每个请求（并自动缓存和刷新）。

即使没有凭据，服务端也会启动，以便客户端列出可用工具； 设置凭据之前，工具调用会返回可操作的配置错误。

选择要提供的工具

每个会话中，一百个工具定义都会占用上下文，而客户端看到一份扁平列表时，无法区分读取操作和删除操作。两个开关可以解决这个问题：

变量	默认值	说明
ASC_TOOLS	all	要提供的逗号分隔工具组，或预设值 core。
ASC_READ_ONLY	0	仅提供无法修改帐户的工具。
ASC_TOOL_DISCOVERY	0	仅公开 search_tools、get_tool_details 和 call_discovered_tool；已筛选的领域工具仍可通过发现功能使用。

ASC_TOOLS=core                     # 41 tools: generic, apps, versions, assets, testflight, submission
ASC_TOOLS=testflight,provisioning  # just what a build-distribution agent needs
ASC_READ_ONLY=1                    # 35 read-only tools; writes are withheld entirely
ASC_TOOL_DISCOVERY=1               # 3 visible tools; discover domain tools on demand

工具组：generic、apps、iap、subscriptions、versions、pricing、 availability、submission、testflight、provisioning、assets、offers、 offer-codes、promotions、reviews、users、events、xcode-cloud、 analytics、custom-product-pages，以及 all 和 core。无法识别的名称会在 stderr 上发出警告，且不会提供任何工具，而不会悄悄回退到全部工具。

在只读模式下，appstore_request 会保留，但拒绝任何非 GET 方法，因此仍可通过这个后备入口访问没有精选工具覆盖的端点， 又不会成为绕过限制的途径。

每个已提供的工具都会声明 MCP 注解（readOnlyHint、destructiveHint、 idempotentHint），客户端会据此判断哪些操作需要确认。九个工具被标记为破坏性操作：七个 delete_*/remove_* 工具、expire_build、 disable_bundle_id_capability，以及 appstore_request（它可以访问任何 DELETE 端点）。

发现模式。 按任务搜索，查看匹配工具的完整输入架构和安全注解，然后将其准确名称和参数传给 call_discovered_tool。ASC_TOOLS 和 ASC_READ_ONLY 会在搜索或执行前筛选私有目录。直接调用隐藏工具名称会失败。 这是服务端发现：查看到的架构会出现在工具结果中，而不是作为新的 MCP 一等工具由宿主注入。 启用写入时，通用执行工具会被标记为破坏性操作；宿主无法针对每个隐藏工具应用不同的审批规则。调用前请检查底层工具并批准写入操作。默认模式保留现有的逐个注解工具界面。

调优

默认值经过选择，可避免工具调用挂起，也可避免单个响应淹没 Agent 的上下文。以下设置均为可选项。

变量	默认值	说明
ASC_TIMEOUT_SECS	60	整个请求的超时时间。0 表示禁用。
ASC_CONNECT_TIMEOUT_SECS	10	连接超时时间。0 表示禁用。
ASC_TRANSFER_TIMEOUT_SECS	300	资源上传和报告下载的超时时间。
ASC_MAX_RETRIES	3	首次尝试之后的重试次数。0 表示禁用。
ASC_MAX_RESPONSE_BYTES	60000	工具结果的大小上限。0 表示禁用。
ASC_COMPACT_RESPONSES	1	从响应中移除冗余的 JSON:API 链接。

重试。 无论使用哪种方法，429 都会重放，因为 Apple 已拒绝请求，且未应用请求内容。对于 5xx 或传输过程中的超时，仅会重放 GET/PATCH/PUT/DELETE 请求——绝不会重放 POST，否则可能会创建重复资源（而且 Apple 会永久保留产品 ID 等标识符）。退避时间采用带抖动的指数增长，并遵循 Retry-After。

响应整形。 结果会以紧凑格式序列化——相同内容的缩进 JSON 字节数是其 1.72×，因此同样的预算现在能承载约 40% 更多的请求数据。每个资源的 self 链接和仅包含链接的关系会被移除：不会丢失任何可寻址内容，而且分页所需的 links.next 会保留。如果响应仍超过预算，会先丢弃 included，然后丢弃末尾的 data 项；结果中会包含一个 _truncated 键，说明缺失了什么以及如何缩小查询范围。请注意，裁剪后继续跟随 links.next 会跳过已丢弃的项目——请改用更小的 limit 重新请求。

构建与运行

cargo build --release
ASC_ISSUER_ID=... ASC_KEY_ID=... ASC_PRIVATE_KEY_PATH=/path/AuthKey_XXX.p8 \
  ./target/release/appstore-mcp

服务通过 stdio 使用 MCP 通信。日志输出到 stderr；stdout 是协议通道。

与 MCP 客户端搭配使用

客户端配置示例（例如 Claude Desktop 的 mcpServers）：

{
  "mcpServers": {
    "appstore": {
      "command": "/absolute/path/to/appstore-mcp/target/release/appstore-mcp",
      "env": {
        "ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "ASC_KEY_ID": "ABCD123456",
        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_ABCD123456.p8"
      }
    }
  }
}

使用 MCP Inspector 检查

npx @modelcontextprotocol/inspector ./target/release/appstore-mcp

使用说明

• ID 是不透明的。 先列出/获取应用、IAP、订阅、集合和价格点，以解析其 ID，然后将这些 ID 传递给创建/更新工具。
• 定价需要价格点。 使用 list_iap_price_points / list_subscription_price_points 获取 set_iap_price_schedule / set_subscription_price 所需的 id。
• 资源上传（upload_*）接受本地文件路径，并在一次调用中执行完整的预留 → 分块上传 → MD5 提交流程。文件采用流式传输，因此峰值内存占用为一个数据块，而非资源的大小；失败的数据块会单独重试。截图/预览需要已有的 appScreenshotSet / appPreviewSet；如有需要，可使用通用工具创建。
• 分页。 appstore_list 默认返回一页。传入 max_pages（最多为 20）即可跟进 links.next 并将各页合并为一个结果 — meta.hasMore 会告知是否还有剩余内容。
• 分析数据。 request_analytics_report → list_analytics_reports → list_analytics_report_instances → list_analytics_report_segments 会返回预签名的分段 URL；download_analytics_segment 会获取该 URL、解压 gzip，并以 JSON 格式返回行数据。对于新请求，Apple 可能需要最多 48 小时才能生成首份报告。
• 未列出的任何内容都可通过 appstore_request（原始方法 + 路径 + JSON:API 请求体）或 appstore_list（分页 GET）访问。示例： appstore_request { "method": "GET", "path": "/v1/apps/123/customerReviews" }。
• 不在支持范围内： 销售/财务报告端点返回 gzip 压缩的 TSV（而非 JSON:API），因此不在这些工具的支持范围内。

限制（由 Apple 强制执行）

• 无法通过 API 创建应用。 apps 资源仅允许 GET 和 UPDATE — POST /v1/apps 会返回 403 FORBIDDEN_ERROR。请在 App Store Connect 网站（Apps → ➕ → New App）中创建应用记录；你可以使用 create_bundle_id 预先创建其 bundle ID。其他所有工具都针对已有应用操作。
• 已删除的应用内购买项目的 productId 会被 Apple 永久保留，无法再次使用。

开发

cargo test                              # 200+ tests, no network or credentials needed
cargo clippy --all-targets -- -D warnings
cargo fmt --check

测试分为三个层次：针对请求体构建器、重试决策和响应整形的纯单元测试；使用 wiremock 测试真实 HTTP 客户端与模拟 API 的交互（重试、超时、分页、三步上传协议、分段下载）；以及 tests/tool_surface.rs，用于断言客户端实际看到的内容符合不变量 — 名称唯一、描述真实、对象架构正确、注释正确，并且 ASC_TOOLS/ASC_READ_ONLY 准确隐藏其声明要隐藏的内容。

最低支持的 Rust 版本为 1.88，并由专门的 CI 作业检查。

添加/更改工具后，请重新生成工具参考（需要发布版二进制文件；无需凭据）：

cargo build --release && python3 scripts/gen_tools_doc.py   # rewrites docs/TOOLS.md

实时集成测试

scripts/integration_test.py 会使用真实 API 驱动已编译的服务。默认只读；--write 会添加一个自动清理的 IAP 生命周期测试。

cargo build --release
# Credentials via env (ASC_ISSUER_ID/ASC_KEY_ID/ASC_PRIVATE_KEY_PATH) or local
# appstore-connect.txt + AuthKey_*.p8 in the repo root (both gitignored).
python3 scripts/integration_test.py --app <APP_ID>          # read-only sweep
python3 scripts/integration_test.py --app <APP_ID> --write  # + write lifecycle

许可证

MIT