play-store-mcp

Local stdio MCP server for Google Play Console. Credentials (a Google service-account key) come only from environment variables; OAuth tokens are minted locally by google-auth-library; every request goes directly to *.googleapis.com. Nothing is sent to any third party.

TypeScript reimplementation — the Kotlin project antoniolg/play-store-mcp was used only as a reference for the API flow and tool design.

Available tools

23 tools, grouped by capability.

Releases & rollout

Tool	Description	Key inputs
get_releases	Current releases/deployments per track	packageName
deploy_app	Upload an APK/AAB and assign it to a track (optional staged rollout)	packageName, track, filePath, versionCode, releaseNotes?, rolloutPercentage?
promote_release	Promote an existing version from one track to another	packageName, fromTrack, toTrack, versionCode
update_track_rollout	Change a staged-rollout fraction, or halt/complete the in-progress release	packageName, track, userFraction?, status?
complete_all_rollouts	Batch-complete the in-progress staged rollout across multiple apps	packageNames[], track?, versionCode?
update_release_notes	Set release notes on the current release of a track (no redeploy)	packageName, notes[], track?

Store listing

Tool	Description	Key inputs
get_listings	Store listing text (title, short/full description) for every locale	packageName
update_listing	Update a store listing for one locale and commit	packageName, language, title?, shortDescription?, fullDescription?
get_app_details	App-level details (default language, contact email/phone/website)	packageName
upload_listing_image	Upload a store-listing graphic (icon, screenshots, feature graphic, …) for a locale	packageName, language, imageType, filePath

Reviews

Tool	Description	Key inputs
get_reviews	Recent user reviews (rating, text, app version, device)	packageName, maxResults?, translationLanguage?
reply_to_review	Post a developer reply to a user review	packageName, reviewId, replyText

Monetization

Tool	Description	Key inputs
list_in_app_products	List managed in-app products (SKUs)	packageName
list_subscriptions	List subscription products	packageName
update_in_app_product	Update an existing managed IAP (status / default price) and commit	packageName, sku, status?, defaultPrice?
get_voided_purchases	List refunded/revoked (voided) purchases	packageName
refund_order	Refund a single order, optionally revoking the entitlement	packageName, orderId, revoke?

Testers

Tool	Description	Key inputs
manage_testers	Read (omit groups) or set the Google Groups of testers for a closed track	packageName, track, googleGroups?

Analytics & reports

Tool	Description	Key inputs
get_users_by_version	Distinct users per app version over N days (Reporting API)	packageName, days?
get_app_vitals	Latest crash rate and ANR rate (Reporting API)	packageName, days?
get_install_stats	Install base per app version + monthly net growth, from the statistics GCS reports	packageName, month?
get_install_reports	Raw install/uninstall report rows for one month and dimension, from the statistics GCS reports	packageName, month, dimension?

Meta

Tool	Description	Key inputs
search_apps	List the apps this service account can access (Reporting API)	—

get_users_by_version uses the Reporting API's vitals-scoped distinctUsers metric — a proxy for the active user base, ideal for the version-adoption split, not an exact install count (the Reporting API has no install-count metric; real install counts live in the statistics GCS reports, read by get_install_stats and get_install_reports).

get_install_reports reads stats/installs/installs_{package}_{YYYYMM}_{dimension}.csv (dimension ∈ overview | country | app_version, default overview) from the reports bucket. These CSVs are UTF-16LE with a BOM; the server decodes and parses them. Set PLAY_REPORTS_BUCKET (Play Console → Download reports → Statistics → Copy Cloud Storage URI; the pubsite_prod_* value) and grant the service account Storage Object Viewer on it.

Setup

1. Google Cloud: create a project, enable Google Play Android Developer API and Google Play Developer Reporting API, create a service account, and download its JSON key.
2. Play Console → Users and permissions: invite the service-account email; grant it the apps and the "View app information / bulk reports" + "Releases" permissions.
3. Configure the MCP (~/.claude.json):

{
  "mcpServers": {
    "play-store": {
      "command": "npx",
      "args": ["-y", "github:petropentsak/play-store-mcp"],
      "env": {
        "PLAY_SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/service-account-key.json",
        "PLAY_DEFAULT_TRACK": "internal"
      }
    }
  }
}

PLAY_SERVICE_ACCOUNT_KEY (raw or base64 JSON) is accepted as an alternative to the path.

Build / release

dist/ is committed so npx github: works with no build step. The config is not pinned to a tag — it tracks the default-branch HEAD, so every commit must be installable (build + commit dist/). To ship: npm run build → commit (incl. dist/) → push HEAD to the default branch → clear ~/.npm/_npx if a stale tarball is cached → reconnect / cold-start the MCP client.