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

도구

appId는 get_releases와 get_reviews에서 선택값입니다. 생략하면 도구가 보유한 모든 앱을 전체적으로 순회합니다. 이것이 포트폴리오 보기입니다.

두 스토어를 위한 하나의 용어

App Store는 appVersionState를 가진 appStoreVersions를 사용하고, Play 출시 내역은 트랙 단위에 담긴 릴리즈에 status와 롤아웃 비율을 사용합니다. 양쪽은 모두 정규화됩니다:

각 스토어의 고유한 표현은 rawState로 보존되므로, 번역 과정에서 잃는 것은 없습니다.

설정

MCP 레지스트리에 io.github.JohnBilousov/appstore-play-mcp로 등록되어 있어, 레지스트리를 읽는 클라이언트는 자체적으로 그대로 검색할 수 있습니다.

두 스토어는 각각 독립적으로 동작합니다. 하나, 둘, 혹은 하나도 구성하지 않아도 됩니다(데모 모드). 참고로 명확하게 말하면 선택값입니다.

App Store Connect에서 → 사용자 및 액세스 → 통합 → App Store Connect API로 이동하고 키를 생성한 뒤 .p8 파일을 다운로드합니다 (Apple은 한 번만 다운로드할 수 있게 합니다).

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

이 서버는 자체적으로 ES256 JWT 서명을 합니다. fastlane이나 추가 의존성이 필요 없습니다. CI에서는 ASC_PRIVATE_KEY에 키를 자체(인라인)로 넣는 대신 사용할 수 있습니다.

Google Cloud에서 서비스 계정을 만들고, 해당 프로젝트에 Android Publisher API를 활성화한 다음, Play Console → 사용자 및 권한에 접근 권한을 부여합니다.

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

PLAY_PACKAGES는 선택 사항이 아닙니다. Play API에는 개발자의 앱 목록을 보여주는 엔드포인트가 없으므로 패키지를 미리 계정해야 합니다. CI에서는 PLAY_SERVICE_ACCOUNT_JSON이 JSON을 자체(인라인)으로 사용합니다.

{
  "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 Code:

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

알아 두면 좋은 플랫폼 제한

다음은 서버의 제한이 아니라 스토어 측의 제약 사항들입니다.

• Play는 사용자의 앱을 목록으로 보여줄 수 없습니다. 그래서 PLAY_PACKAGES가 필요한 것입니다.

• Play 리뷰는 약 일주일 단위로만 제공되며, 실제로 리뷰가 존재하는 앱에서만 얻을 수 있습니다.

• Play 트랙 데이터는 "수정"에 들어갔을 때만 읽을 수 있습니다. 여기서 수행하는 모든 읽기 작업은 임시 "edit"를 열고 finally 블록에서 제거합니다. 실제 데이터가 커밋되는 것은 절대 아니므로 애프 헥션이 수정되는 않지만, 그래서 읽기 전용 서버가 POST를 하는 것입니다.

• App Store 리뷰는 국가/지역별로 분리되어 스토어 페이지에 반영되는 것보다 몇 시간 정도 지연될 수 있습니다.

디자인 노트

자격 증명 두 개, 인터페이스 하나. AppStoreClient와 PlayClient는 모두 StoreClient를 구현합니다. DemoStoreClient는 이 인터페이스를 세 번째로 픽스처에 구현합니다. 도구들은 이야기하는 스토어에 따라 분기하지 않습니다.

스토어 하나가 죽어도 호출 전체가 죽지는 않습니다. 읽기는 Promise.allSettled로 분산됩니다. Play가 다운되어도 App Store의 리뷰는 계속 반환되며 무슨 데이터가 누락되었는지 설명하는 메모가 함께 나타납니다. 빈 목록과 깨진 자격 증명은 결코 같아 보이는 일이 없어야 합니다.

오류가 해결 방법을 함께 제공합니다. Play에서 403이 뜨면 서비스 계정에 권한이 없는 것이거나 해당 프로젝트에서 Android Publisher API가 아직 활성화되지 않았을 수 있다는 뜻입니다. 404는 list_apps를 호출하라고 안내합니다. 일반적으로 모델은 사용자 개입 없이 스스로 회복할 수 있습니다.

토큰은 캐시되고 제때 갱신됩니다. Apple용 ES256(20분), Google용 RS256 → OAuth2(1시간)는 만료 1분 전에 갱신되기 때문에 호출이 만료를 두고 경쟁할 이유가 없습니다.

개발

git clone https://github.com/JohnBilousov/appstore-play-mcp && cd appstore-play-mcp
npm install
npm run build
npm test          # tool surface, state normalisation, and portfolio sweeps over a real MCP transport
npm run inspect

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

로드맵

• App Store Connect에서 판매 및 다운로드 보고서 (벤더 번호 필요)

• Play Developer Reporting API에서 크래시 및 ANR 바이탈 확보

• TestFlight 빌드 및 테스터 그룹 지원

• stdio와 함께 streamable HTTP 트랜스포트 확보

• MCP 레지스트리에 게시

기여는 언제나 환영합니다. 특히 두 스토어에 모두 출시해 보고 위에 기록할 만한 제약을 직접 겪어본 분들의 실전 경험이 큰 도움이 됩니다.

License

MIT © Ivan Bilousov