Google Play Store

Secure, dry-run-first Google Play Store listing automation for humans, CI, and MCP agents.

This project manages Google Play Store listing text through the official Android Publisher API. It is intentionally not a browser automation tool and does not depend on fastlane at runtime.

Why This Exists

Google Play listing work has two very different operators:

• Humans and CI need a CLI that can export, diff, validate, and apply listing metadata.
• Agents need an MCP server with safe tools that preview changes before committing them.

Both surfaces share one core library so security behavior, diffing, validation, and apply semantics stay consistent.

Repo Layout

packages/core   Typed Android Publisher API client, listing manifests, diff, validate, apply
packages/cli    gpstore command for humans and CI
packages/mcp    MCP stdio server for agent tools
examples        Safe example metadata, with no credentials
docs            Security and operating notes

Roadmap

Read ROADMAP.md for the current plan. Screenshot and media replacement details live in docs/media-roadmap.md.

Current Capabilities

• Export current localized listing text from Google Play.
• Load fastlane/supply-style metadata directories.
• Preview exact localized text changes.
• Stage and validate Google Play edits without committing them.
• Commit listing text only with explicit confirmation.
• Use service-account JSON from a local file path only.
• Redact and avoid logging secrets.

Screenshots and media asset replacement are designed into the core client as Android Publisher image primitives, but the first public workflow focuses on listing text. The screenshot pipeline should come next as a manifest-driven media diff/apply flow.

Install

This repo is scaffolded as an npm workspace. After cloning:

npm install
npm run build

For local MCP usage after build:

{
  "mcpServers": {
    "google-play-store": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-store-mcp/packages/mcp/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account.json"
      }
    }
  }
}

CLI Usage

Use a fastlane/supply-style metadata directory:

metadata/android/en-US/title.txt
metadata/android/en-US/short_description.txt
metadata/android/en-US/full_description.txt
metadata/android/es-US/title.txt
metadata/android/es-US/short_description.txt
metadata/android/es-US/full_description.txt

Preview changes:

gpstore diff \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json

Validate with Google Play and discard the edit:

gpstore validate \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json

Apply only after review:

gpstore apply \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json \
  --confirm APPLY_GOOGLE_PLAY_LISTING_CHANGES

Export current listing metadata:

gpstore export \
  --package-name com.example.app \
  --out ./metadata/android \
  --credentials /absolute/path/to/service-account.json

MCP Tools

• play_listing_diff: dry-run listing diff.
• play_listing_validate: stages listing changes in a Google Play edit, validates them, then deletes the edit.
• play_listing_apply: commits listing changes only when confirm is exactly APPLY_GOOGLE_PLAY_LISTING_CHANGES.
• play_listing_export: returns current localized listing text as structured JSON.

MCP clients should still ask the user before calling play_listing_apply, because it modifies a cloud-managed public store listing.

Security Model

Read docs/security.md before using this with a real app.

Short version:

• No browser scraping.
• No credential upload.
• No credential persistence.
• No raw service-account JSON in config files.
• Dry-run and validation before apply.
• Apply requires explicit confirmation.
• Use least-privilege Play Console service accounts.

Official API References

• Android Publisher API overview: https://developer.android.com/google/play/developer-api
• Localized listing updates: https://developers.google.com/android-publisher/api-ref/rest/v3/edits.listings/update
• Android Publisher media uploads: https://developers.google.com/android-publisher/upload
• MCP TypeScript SDK: https://modelcontextprotocol.io/docs/sdk