App Store & Google Play

appstore-play-mcp

一个用于 App Store Connect 和 Google Play 的只读 MCP 服务。通过一套工具访问两个商店，这样你只需问一次“哪些已上线、哪些正在审核、用户都在抱怨什么？”，而不必问两次。

> Which of my apps have a release that isn't live yet?

  Pocket Herbarium (App Store)
    app-store: 2.1.0 (214) — in review
  Pocket Herbarium (Google Play)
    production: 2.0.3 (208) — rolling out at 20%
    beta: 2.1.0 (214) — live

专为同时向两个商店发布应用、厌倦了面对两套控制台、两种身份验证方案，以及同一事物的两套术语的独立开发者打造。

这里的任何操作都不会写入数据。 不修改元数据、不提交应用、不回复审核意见。每个工具都标注了 readOnlyHint，测试套件也会在这一点不再成立时失败。

30 秒快速体验

无需 Apple 密钥，也无需 Google 服务账号：

npx -y appstore-play-mcp --demo

演示模式会提供一个虚构的双应用开发者的示例数据，包括一个卡在审核中的版本，以及一个进度为 20% 的分阶段发布，因为这些才是值得关注的状态。

npx @modelcontextprotocol/inspector npx -y appstore-play-mcp --demo

工具

get_releases 和 get_reviews 中的 appId 是可选的。省略它，工具就会遍历你拥有的所有应用，呈现整个应用组合的视图。

统一两个商店的术语

App Store 使用带有 appVersionState 的 appStoreVersions；Play 使用包含版本的发布轨道，版本带有 status 和发布比例。两者都会归一化：

每个商店自己的表述都会保留在 rawState 中，因此不会丢失任何信息。

评价也会经过同样的处理，但有一个必须如实说明的例外：两个商店对于评价来源的信息报告方式不同，因此不会共用同一个字段。

如果把语言合并到国家字段中，统一后的结构看起来会更整齐，却会报告错误信息。因此，每个商店只会填入自己实际掌握的信息。

设置

已在 MCP Registry 中登记为 io.github.JohnBilousov/appstore-play-mcp，因此读取该注册表的客户端可以自行发现它。

任一应用商店都可以独立使用——配置一个、两个，或都不配置（使用 fixtures）。

export ASC_KEY_ID=XXXXXXXXXX
export ASC_ISSUER_ID=00000000-0000-0000-0000-000000000000
export ASC_KEY_PATH=/path/to/AuthKey_XXXXXXXXXX.p8

export PLAY_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
export PLAY_PACKAGES=com.example.app,com.example.other

{
  "mcpServers": {
    "stores": {
      "command": "npx",
      "args": ["-y", "appstore-play-mcp"],
      "env": {
        "ASC_KEY_ID": "XXXXXXXXXX",
        "ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "ASC_KEY_PATH": "/path/to/AuthKey_XXXXXXXXXX.p8",
        "PLAY_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json",
        "PLAY_PACKAGES": "com.example.app"
      }
    }
  }
}

claude mcp add stores -- npx -y appstore-play-mcp

值得了解的平台限制

这些是应用商店的限制，而非服务器的限制：

• Play 无法列出你的应用。 因此需要设置 PLAY_PACKAGES。
• Play 的评论只能追溯约一周，且只有有评论的应用才会返回评论。
• 只有在“编辑”中才能读取 Play 轨道数据。 这里的每次读取都会创建一个临时编辑，并在 finally 块中将其删除。任何内容都不会提交，因此不会修改你的应用——但这就是只读服务器会发出 POST 请求的原因。
• App Store 评论按地区划分，显示可能比商店页面晚几个小时。

设计说明

两种凭据，一个接口。 AppStoreClient 和 PlayClient 都实现了 StoreClient；DemoStoreClient 则在 fixtures 上实现了该接口。工具无需区分正在与哪个应用商店交互。

一个应用商店故障不会导致整个调用失败。 读取操作会并行访问各个应用商店和应用，任何一处故障都会被收集，而不会抛出异常。如果 Play 不可用，仍会返回 App Store 评论——文本中会注明 Play 故障，并在 unavailable 中列出，让模型可以告知用户结果不完整。空列表与凭据失效绝不能表现得一样；有测试专门验证这一点。

错误信息会提供解决方法。 Play 返回 403 时会提示服务账号可能缺少访问权限，或者其项目可能未启用 Android Publisher API。返回 404 时会提示调用 list_apps。模型通常可以在无需用户介入的情况下恢复。

令牌会缓存并提前刷新。 Apple 使用 ES256（20 分钟），Google 使用 RS256 → OAuth2（1 小时），两者都会在过期前一分钟刷新，避免调用恰好遇到过期时刻。Play 端还会缓存正在进行的令牌交换：listApps() 会为每个软件包并发创建一个编辑；如果没有这一机制，每个并发调用方都会发现尚无缓存令牌，并各自创建一个令牌。

开发

git clone https://github.com/JohnBilousov/appstore-play-mcp && cd appstore-play-mcp
npm install
npm run build
npm test          # tool surface + both auth clients against a mocked fetch, real key material throughout
npm run lint      # eslint
npm run format    # prettier --write
npm run inspect

每次推送和拉取请求都会由 CI 运行 typecheck、lint、format:check、test 和 build。

src/
  index.ts          CLI entry, stdio transport
  config.ts         env → Config; either store optional, fixtures as the floor
  server.ts         tools + the registry that fans reads across stores
  schemas.ts        zod input and output shapes
  format.ts         human-readable summaries next to structuredContent
  stores/
    types.ts        shared vocabulary + state normalisation
    appstore.ts     App Store Connect (ES256 JWT)
    play.ts         Google Play (service account → OAuth2)
    demo.ts         fixtures
test/
  server.test.ts    tool surface, state normalisation, portfolio sweeps — over a real MCP transport
  stores/
    appstore.test.ts  ES256 signing verified against the public key, token caching, error mapping
    play.test.ts       RS256/OAuth2 exchange, the transient-edit cleanup, the concurrency fix above

发布

发布使用 npm 的可信发布（OIDC）—— 无需 NPM_TOKEN 密钥，也没有任何可能泄露或过期的凭据。只需在 npmjs.com 上进行一次设置：进入软件包的 Settings → Trusted publishing → GitHub Actions，填写组织 JohnBilousov、此存储库以及工作流文件名 publish.yml。

要发布新版本：同时更新 package.json、server.json 和 src/server.ts 中的 VERSION（测试会确保它们始终一致），提交并推送，然后发布带有匹配 vX.Y.Z 标签的 GitHub Release。此操作会触发 .github/workflows/publish.yml，运行测试套件并通过来源证明发布到 npm——软件包页面会显示可追溯到此确切提交和工作流运行的已验证链接，而不只是注册表上的一个名称。

路线图

• 来自 App Store Connect 的销售和下载报告（需要供应商编号）
• 来自 Play Developer Reporting API 的崩溃和 ANR 指标
• TestFlight 构建和测试者群组
• 除 stdio 外，支持 Streamable HTTP 传输

欢迎贡献——尤其欢迎同时向两个应用商店发布应用，并遇到值得在此记录的限制的开发者。

许可证

MIT © Ivan Bilousov