appstore-play-mcp

Un servidor MCP de solo lectura para App Store Connect y Google Play. Un mismo conjunto de herramientas para ambas tiendas, de forma que puedes preguntar «¿qué está publicado, qué está en revisión y de qué se queja la gente?» una sola vez en lugar de dos.

> 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

Pensado para desarrolladores independientes que publican en ambas tiendas y están cansados de dos consolas, dos esquemas de autenticación y dos vocabularios para la misma cosa.

Aquí no se escribe nada. Sin ediciones de metadatos, sin envíos, sin respuestas a reseñas. Cada herramienta está anotada con readOnlyHint, y la suite de pruebas falla si eso deja de ser cierto en algún momento.

Pruébalo en 30 segundos

Sin clave de Apple, sin cuenta de servicio de Google:

npx -y appstore-play-mcp --demo

El modo demo sirve datos de ejemplo de un desarrollador ficticio con dos aplicaciones, incluida una versión atascada en revisión y un despliegue gradual al 20 %, porque esos son los estados que merece la pena revisar.

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

Herramientas

appId es opcional en get_releases y get_reviews. Si no lo incluyes, la herramienta recorre todas las aplicaciones que tengas: esa es la vista de cartera.

Un solo vocabulario para dos tiendas

App Store tiene appStoreVersions con un appVersionState; Play tiene tracks que contienen lanzamientos con un status y una fracción de despliegue (rollout). Ambos se normalizan:

La terminología propia de cada tienda se conserva en state, de modo que no se pierde nada en la traducción.

Configuración

Está listado en el registro MCP como io.github.JohnBilousov/appstore-play-mcp, para que los clientes que leen el registro puedan encontrarlo sin ayuda.

Cualquiera de las dos tiendas funciona por sí sola: configura una, ambas o ninguna (datos de ejemplo).

En App Store Connect → Usuarios y acceso → Integraciones → API de App Store Connect, crea una key y descarga el .p8 (Apple descargas es exactamente una vez).

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

El servidor firma su propio JWT ES256: no stem 필요 fastlane ni dependencias adicionales. ASC_PRIVATE_KEY acepta la clave directamente, para CI.

Crea una cuenta de servicio en Google Cloud, habilita la Android Publisher API para su proyecto y concede acceso en Play Console → Usuarios y permisos.

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

PLAY_PACKAGES no es opcional: la API de Play.no dispone de ningún endpoint que liste las aplicaciones de un desarrollador, así que hay que declarar los paquetes. PLAY_SERVICE_ACCOUNT_JSON acepta el JSON directamente, para 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

Límites de las plataformas que conviene conocer

Estos son límites de las tiendas de aplicaciones, no del servidor:

• Play no puede listar tus aplicaciones. Por eso existe PLAY_PACKAGES.

• Las reseñas de Play llegan a cubrir aproximadamente una semana, y solo existen para aplicaciones que tienen reseñas.

• Los datos de tracks de Play solo se pueden leer dentro de un «edit». Cada lectura crea un edit transitorio y lo elimina en un bloque finally. Nunca se confirma nada, por lo que tu aplicación no se modifica; esa es la razón por la que un servidor de solo lectura hace un POST.

• Las reseñas de App Store son por territorio y pueden retrasarse respecto a la página de la tienda en unas horas.

Notas de diseño

Dos credenciales, una sola interfaz. AppStoreClient y PlayClient implementan StoreClient; DemoStoreClient hace una tercera implementación sobre datos de ejemplo. Las herramientas nunca classify según la tienda a la que se dirigen.

Que falla un dé una tienda no se lleva por delante la llamada. Las lecturas se lanzan en abanico con Promise.allSettled. Si Play cae, las reseñas de App Store se pueden deep igual, incluso con una nota explicando qué falta. Una lista vacía y una credencial rota no deberían parecerse nunca.

Los errores incluyen la solución. Un 403 de Play indica que la cuenta de servicio podría no tener acceso o que Android Publisher API podría estar deshabilitada para ese proyecto. Un 404 dice que hay que llamar a list_apps. Por lo general, el modelo puede recuperarse sin que intervenga el usuario.

Los tokens se almacenan en caché y se renuevan con antelación. ES256 para Apple (20 min), RS256 → OAuth2 para Google (1 hora); ambos se renuevan un minuto antes de que expire el tiempo, para que ninguna llamada compita con ese límite.

Desarrollo

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

Hoja de ruta

• Informes de ventas y descargas de App Store Connect (requiere proveedor)

• Crheshes y ANR vitals de la Play Developer Reporting API

• Builds de TestFlight y grupos de tester

• Soporte de transporte Streamable HTTP además de stdio

• Publicar en el registro MCP

Las contribuciones son bienvenidas, especialmente de quienes publican en ambas tiendas y se han chocado con un límite que merezca la pena documentar aquí.

Licencia

MIT © Ivan Bilousov