npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

gplay-mcp

v0.2.0

Published

Model Context Protocol (MCP) server and CLI for Google Play Console and Android Developer API

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>.
  • Atomic Google Play Edits Transactions:
    • Automatically manages the edits.insert ➔ modify ➔ edits.commit lifecycle behind the scenes.
    • Automatically aborts and deletes (edits.delete) dangling edits if any step fails, preventing orphaned locks on Google Play Console.
  • 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 .aab bundles, 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.
  • 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?

  1. No API Endpoint (applications.create does not exist):
    • Google's official Android Developer API intentionally does not provide any endpoint to register a new application.
  2. 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

  1. Go to Google Play Console.
  2. Navigate to Developer account ➔ API access.
  3. 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:

  1. Google Play Android Developer API (Required for releases, bundles, store listings, reviews, and monetization).
  2. 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 disabled visit 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.json is 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.json is 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)

  1. In Google Cloud Console, open APIs & Services ➔ Credentials.
  2. Click Create Credentials ➔ OAuth client ID.
  3. Select Application type: Web application.
  4. Set Authorized redirect URIs:
    http://localhost:3456/callback
  5. Copy your Client ID and Client Secret.
  6. Run the authentication command:
    gplay-mcp auth --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET>
    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.

Option B: Service Account (Recommended for CI/CD & servers)

  1. In Google Cloud Console, open IAM & Admin ➔ Service Accounts.
  2. Click Create Service Account (e.g. [email protected]).
  3. Click on the created service account, go to Keys ➔ Add Key ➔ Create new key (JSON format). Download the JSON key file.
  4. 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:

| 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. |

  1. Click Invite user (or Save changes).
  2. 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