gplay-mcp
v0.2.0
Published
Model Context Protocol (MCP) server and CLI for Google Play Console and Android Developer API
Maintainers
Readme
gplay-mcp
Model Context Protocol (MCP) server & CLI for Google Play Console and Android Developer API.
Turn your AI assistants (Claude Desktop, Cursor, Antigravity, etc.) into autonomous Android release, store listing, vitals monitoring, and customer review management engines.
✨ Features
- Dual-Layer Authentication:
- Interactive OAuth 2.0 (Developer Friendly): Start a local loopback server (
http://localhost:3456/callback), log in via your default browser, and securely save Refresh Tokens to your OS Keychain (@napi-rs/keyring). - Headless / Service Account (CI/CD & Server Friendly): Seamlessly authenticate using
GOOGLE_APPLICATION_CREDENTIALS,GPLAY_SERVICE_ACCOUNT_KEY, or--key-file <path>.
- Interactive OAuth 2.0 (Developer Friendly): Start a local loopback server (
- Atomic Google Play Edits Transactions:
- Automatically manages the
edits.insert➔modify➔edits.commitlifecycle behind the scenes. - Automatically aborts and deletes (
edits.delete) dangling edits if any step fails, preventing orphaned locks on Google Play Console.
- Automatically manages the
- Full Suite of 19 MCP Tools:
- Apps Discovery: List all accessible apps on your Play Console account (
play_apps_list). - Releases & Builds: List tracks, upload
.aabbundles, create releases, and control staged rollout percentages. - Store Listing & ASO: Fetch and update title/descriptions in any language, upload icons and screenshots.
- Reviews & Feedback: List user ratings/reviews and reply to customers.
- Android Vitals & Quality: Query user-perceived crash rates and ANR rates directly from the Reporting API.
- Monetization & IAP: List in-app products and subscription base plans.
- Apps Discovery: List all accessible apps on your Play Console account (
- Built on
mcponce:- Single-executable stdio bridge with optional background daemon support.
- Parameter coercion and Zod-backed schemas.
- Biome code quality and Node.js native test runner.
⚠️ Important Note: New App Creation
[!WARNING]
🚫 Can I create a new app on Google Play with this tool?
No. It is impossible to create a brand-new app entity via API in the Google Play ecosystem (neither with this tool nor any other API-based tool).
🔍 Why does Google enforce this?
- No API Endpoint (
applications.createdoes not exist):
- Google's official Android Developer API intentionally does not provide any endpoint to register a new application.
- Mandatory Policy & Regulatory Declarations:
- Google requires developers to complete interactive forms manually in the Google Play Console web interface:
- Data Safety form
- Target Audience & Content questionnaire
- Financial / Government / Ads Declarations
- Play App Signing key setup and package name reservation
- Google legally mandates developer acknowledgment of these forms in the web console before an app can exist.
✅ What CAN be automated after creating the app?
Once you click "Create app" once in Google Play Console and reserve your package name, 100% of all subsequent lifecycle workflows can be fully managed via
gplay-mcp:
- 🚀 Uploading Android App Bundles (
.aab)- 📦 Creating and rolling out releases (
production,beta,alpha,internal) with staged percentages- 🌐 Managing store listing text (title, short & full description) across all languages
- 🖼️ Uploading app icons, feature graphics, and device screenshots
- 💬 Monitoring user reviews, ratings, and replying to customer feedback
- 📊 Inspecting Android Vitals (user-perceived crash rates and ANR rates)
- 💰 Inspecting in-app products and subscription base plans
🛠️ Installation
npm install -g gplay-mcp
# or run directly with npx
npx gplay-mcp --help🔐 Google Cloud Console & Play Console Setup
To use Google Play APIs, you need to link your Google Play Console to a Google Cloud Project and enable API access.
Step 1: Link Play Console to Google Cloud
- Go to Google Play Console.
- Navigate to Developer account ➔ API access.
- Choose Link an existing Google Cloud project or create a new one.
Step 2: Enable Required APIs in Google Cloud
You must enable the following APIs in your Google Cloud Project:
- Google Play Android Developer API (Required for releases, bundles, store listings, reviews, and monetization).
- Google Play Developer Reporting API (Required for Android Vitals crash rate & ANR metrics).
[!IMPORTANT] If you encounter:
Google Play Android Developer API has not been used in project ... before or it is disabledvisit the link above, ensure your Google Cloud project is selected in the top bar, and click Enable.
⚠️ Common Pitfall: google-services.json vs service-account.json
[!WARNING] Do not use
google-services.json!
google-services.jsonis a client-side config generated for the Android app (Firebase SDK / push notifications). It contains client IDs and public keys, but no server-side private key, so it cannot authenticate Google Play API requests.service-account.jsonis generated from Google Cloud Console ➔ IAM & Admin ➔ Service Accounts. It contains a private key ("private_key": "-----BEGIN PRIVATE KEY...") and client email ("client_email": "[email protected]"). Only this file can be used for Service Account authentication.
Step 3: Configure Authentication (Choose Option A or B)
Option A: Interactive OAuth 2.0 (Recommended for local dev & desktops)
- In Google Cloud Console, open APIs & Services ➔ Credentials.
- Click Create Credentials ➔ OAuth client ID.
- Select Application type: Web application.
- Set Authorized redirect URIs:
http://localhost:3456/callback - Copy your Client ID and Client Secret.
- Run the authentication command:
Your browser will automatically open Google's consent screen. Once approved, the refresh token is stored safely in your macOS Keychain / Windows Credential Manager / Linux Secret Service.gplay-mcp auth --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET>
Option B: Service Account (Recommended for CI/CD & servers)
- In Google Cloud Console, open IAM & Admin ➔ Service Accounts.
- Click Create Service Account (e.g.
[email protected]). - Click on the created service account, go to Keys ➔ Add Key ➔ Create new key (JSON format). Download the JSON key file.
- Back in Google Play Console, go to Users and permissions ➔ Invite new users:
- Paste the service account's email address (e.g.
[email protected]). - Under Account permissions (or per-app under App permissions), check the permissions needed for your use case:
- Paste the service account's email address (e.g.
| Google Play Console Permission | Required By MCP Tools |
| :--- | :--- |
| View app information (read-only) | play_apps_listplay_vitals_crash_rateplay_vitals_anr_rate |
| Release to production, exclude devices, and use Play App Signing | play_release_create (production)play_release_update_rollout |
| Release apps to testing tracks | play_bundle_uploadplay_release_create (beta / alpha / internal) |
| Manage store presence | play_listing_getplay_listing_updateplay_media_upload |
| Reply to reviews | play_reviews_listplay_review_reply |
| View financial data, orders, and cancellation survey responses | play_inapp_listplay_subscriptions_list |
| Admin (all permissions) | Grants access to all 14 tools across all current and future apps. |
- Click Invite user (or Save changes).
- Load the key file into
gplay-mcp:# Option 1: Store in system keychain gplay-mcp auth --key-file ./service-account.json # Option 2: Use environment variable export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
🖥️ CLI Commands
# Authenticate via OAuth 2.0 loopback flow
gplay-mcp auth --client-id <id> --client-secret <secret>
# Authenticate via Service Account JSON key
gplay-mcp auth --key-file ./service-account.json
# Check current authentication status and verify Google API connectivity
gplay-mcp status
# Log out and remove stored credentials from system keychain
gplay-mcp logout
# Run the MCP server over stdio (used by AI assistants)
gplay-mcp run🤖 MCP Client Configuration
Add gplay-mcp to your MCP client configuration file:
Claude Desktop
File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"gplay": {
"command": "npx",
"args": ["-y", "gplay-mcp", "run"]
}
}
}Or with an explicit Service Account key file:
{
"mcpServers": {
"gplay": {
"command": "npx",
"args": ["-y", "gplay-mcp", "run"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account.json"
}
}
}
}Cursor
Add to your Cursor MCP settings (cursor.json or Settings ➔ Features ➔ MCP):
- Name:
gplay - Type:
command - Command:
npx -y gplay-mcp run
Antigravity IDE
Add to your project's mcp_config.json or user configuration:
{
"mcpServers": {
"gplay": {
"command": "npx",
"args": ["-y", "gplay-mcp", "run"]
}
}
}🧰 Available MCP Tools (19 Tools)
All tools automatically manage atomic Play Store edit transactions.
0. Built-in Help (help.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_help | topic (overview, tools, languages, media, releases, auth) | Return structured usage guide, tool reference, language normalization rules, and media guidelines. |
A. Apps Discovery (apps.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_apps_list | pageSize, pageToken | List all Android applications accessible by the authenticated account on Google Play Console. |
B. Releases & Builds (releases.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_releases_list | packageName, track | List active, completed, draft, and halted releases for a track (production, beta, alpha, internal). |
| play_bundle_upload | packageName, filePath | Upload an Android App Bundle (.aab) from local disk into an edit transaction and commit it. |
| play_release_create | packageName, track, versionCodes (or versionCode), status, userFraction, name, releaseNotes | Assign a new release to a track, configuring rollout percentage, status, and release notes. |
| play_release_update_rollout | packageName, track, userFraction, status | Increase staged rollout percentage or pause/complete an active rollout on a track. |
C. Store Listing & ASO (listing.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_listings_list | packageName | List all configured localized store listings and the app's default language. |
| play_listing_get | packageName, language | Retrieve localized title, short description, full description, and video URL. |
| play_listing_update | packageName, language, title, shortDescription, fullDescription, video, changesNotSentForReview | Create a new language listing or update an existing localized listing within an atomic transaction. |
| play_listing_delete | packageName, language, changesNotSentForReview | Delete a localized store listing for a specific language. |
| play_media_list | packageName, imageType, language | List uploaded graphics or screenshots for a language and image type. |
| play_media_upload | packageName, imageType, language, filePath / filePaths, replaceExisting, changesNotSentForReview | Upload one or more icons, feature graphics, TV banners, or screenshots in a single atomic transaction. |
| play_media_delete | packageName, imageType, language, imageId, changesNotSentForReview | Delete a single image by ID or all images for a language and image type. |
D. User Reviews & Feedback (reviews.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_reviews_list | packageName, maxResults, starRating, translationLanguage, token | List user reviews and ratings with optional star rating filters. |
| play_review_reply | packageName, reviewId, replyText | Reply directly to a user review or update an existing developer reply. |
E. Android Vitals & Quality (vitals.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_vitals_crash_rate | packageName, timelineSpec, filter, pageSize, pageToken | Query user-perceived crash rate metrics from Google Play Developer Reporting API. |
| play_vitals_anr_rate | packageName, timelineSpec, filter, pageSize, pageToken | Query user-perceived ANR (Application Not Responding) metrics. |
F. Monetization & IAP (monetization.ts)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| play_inapp_list | packageName, maxResults, token | List in-app one-time products, SKUs, and default prices. |
| play_subscriptions_list | packageName, pageSize, pageToken | List subscription products, base plans, and localized offers. |
🧪 Development & Testing
# Run Biome linter
npm run lint
# Auto-format and fix lints
npm run lint:fix
# Run unit and integration tests
npm test
# Build production bundle
npm run build📄 License
MIT
