appstore-play-mcp

MCP-сервер только для чтения для App Store Connect и Google Play. Один набор инструментов для обоих магазинов, чтобы вы могли спросить «что в проде, что на проверке и на что жалуются пользователи?» один раз, а не два.

> 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 есть appStoreVersions с полем appVersionState; в Play есть треки, содержащие релизы со статусом status и долей раскатки. Всё нормализуется:

Собственная терминология каждого магазина сохраняется в rawState, так что ничего не теряется при переводе.

Настройка

Указан в MCP Registry как 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 и никаких лишних зависимостей. ASC_PRIVATE_KEY принимает ключ инлайн, что удобно для CI.

Создайте сервисный аккаунт в 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 нет эндпоинта, который возвращает список приложений разработчика, поэтому пакеты нужно объявлять. PLAY_SERVICE_ACCOUNT_JSON, в свою очередь, принимает JSON напрямую — для CI.

{
  "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». Каждое чтение здесь открывает временный edit и удаляет его в блоке finally. Ничего никогда не коммитится, поэтому ваше приложение не изменяется — но именно поэтому сервер, работающий только на чтение, делает POST-запрос.

• Отзывы App Store привязаны к территории и могут отставать от страницы магазина на несколько часов.

Заметки по дизайну

Два набора учётных данных — один интерфейс. AppStoreClient и PlayClient реализуют контракт StoreClient; DemoStoreClient реализует его третий раз на фикстурах. Инструменты никогда не ветвятся в зависимости от того, с каким магазином работают.

Сбой одного магазина не роняет запрос. Чтения расходятся через Promise.allSettled. Если Play недоступен, отзывы App Store всё равно возвращаются, и в ответе будет пояснение, чего не хватает. Пустой список и нерабочие учётные данные не должны выглядеть одинаково.

Ошибки содержат готовое решение. 403 от Play означает, что у сервисного аккаунта может не хватать прав или для его проекта может быть отключён Android Publisher API. 404 подсказывает вызвать list_apps. Модель обычно может исправить ситуацию сама, без вмешательства пользователя.

Токены кэшируются и обновляются заранее. ES256 для Apple (20 мин), RS256 → OAuth2 для Google (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 (нужен номер продавца)

• Crash and ANR vitals из Play Developer Reporting API

• Сборки TestFlight и группы тестировщиков

• Транспорт Streamable HTTP в дополнение к stdio

• Публикация в MCP Registry

Вклад приветствуется — особенно от тех, кто выпускает приложения в оба магазина и сталкивался с ограничением, о котором здесь стоит рассказать.

Лицензия

MIT © Ivan Bilousov