appstore-play-mcp

A read-only MCP server for App Store Connect and Google Play. One set of tools over both stores, so you can ask "what's live, what's in review, and what are people complaining about?" once instead of twice.

> 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

Built for indie developers who ship to both stores and are tired of two consoles, two auth schemes, and two vocabularies for the same thing.

Nothing here writes. No metadata edits, no submissions, no review replies. Every tool is annotated readOnlyHint, and the test suite fails if that ever stops being true.

Try it in 30 seconds

No Apple key, no Google service account:

npx -y appstore-play-mcp --demo

Demo mode serves fixtures for a fictional two-app developer — including a version stuck in review and a staged rollout at 20%, because those are the states worth looking at.

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

Tools

appId is optional on get_releases and get_reviews. Leave it out and the tool sweeps every app you have — that's the portfolio view.

One vocabulary for two stores

The App Store has appStoreVersions with an appVersionState; Play has tracks holding releases with a status and a rollout fraction. Both are normalised:

Each store's own wording is preserved in rawState, so nothing is lost in translation.

Reviews get the same treatment, with one honest exception: the stores do not report the same thing about where a review came from, so they do not share a field.

Collapsing a language into a country field would have made the unified shape look tidier and report something false, so each store fills only what it actually knows.

Setup

Listed in the MCP Registry as io.github.JohnBilousov/appstore-play-mcp, so clients that read the registry can find it on their own.

Either store works on its own — configure one, both, or neither (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

Platform limits worth knowing

These are the stores' constraints, not the server's:

• Play cannot list your apps. Hence PLAY_PACKAGES.
• Play reviews go back about a week, and only exist for apps that have reviews.
• Play track data is only readable inside an "edit." Every read here opens a transient edit and deletes it in a finally block. Nothing is ever committed, so your app is not modified — but that is why a read-only server makes a POST.
• App Store reviews are per-territory and can lag the store page by a few hours.

Design notes

Two credentials, one interface. AppStoreClient and PlayClient both implement StoreClient; a DemoStoreClient implements it a third time on fixtures. Tools never branch on which store they are talking to.

One store failing doesn't sink the call. Reads fan out across stores and across apps, and a failure on either axis is collected rather than thrown. If Play is down, App Store reviews still come back — with the Play failure named in the text and listed in unavailable, so the model can tell the user the answer is partial. An empty list and a broken credential must never look the same; a test asserts they don't.

Errors carry the fix. A 403 from Play says the service account may lack access or the Android Publisher API may be disabled for its project. A 404 says to call list_apps. The model can usually recover without the user intervening.

Tokens are cached and refreshed early. ES256 for Apple (20 min), RS256 → OAuth2 for Google (1 hour), both refreshed a minute before expiry so no call races the boundary. The Play side also memoizes the in-flight exchange: listApps() opens an edit per package concurrently, and without that, each concurrent caller would see no cached token yet and mint its own.

Development

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 runs typecheck, lint, format:check, test, and build on every push and pull request.

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

Releasing

Publishing uses npm's trusted publishing (OIDC) — no NPM_TOKEN secret, nothing that can leak or expire. One-time setup on npmjs.com, under the package's Settings → Trusted publishing → GitHub Actions: organization JohnBilousov, this repository, workflow filename publish.yml.

To cut a release: bump the version in package.json, server.json, and VERSION in src/server.ts together (a test asserts they can't drift), commit, push, then publish a GitHub Release with a matching vX.Y.Z tag. That triggers .github/workflows/publish.yml, which runs the test suite and publishes to npm with provenance — the package page shows a verified link back to this exact commit and workflow run, not just a name on the registry.

Roadmap

• Sales and download reports from App Store Connect (needs a vendor number)
• Crash and ANR vitals from the Play Developer Reporting API
• TestFlight builds and tester groups
• Streamable HTTP transport alongside stdio

Contributions welcome — especially from anyone who ships to both stores and has hit a limit worth documenting here.

License

MIT © Ivan Bilousov