google-play-developer-mcp

# google-play-developer-mcp

> **The complete Model Context Protocol (MCP) server for Google Play.**
> 157 tools. Full Android Publisher API v3 + Play Developer Reporting API v1beta1. No deprecated endpoints. Works with Claude, Cursor, VS Code Copilot, Gemini CLI, or any MCP client.

[![npm version](https://img.shields.io/npm/v/google-play-developer-mcp.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/google-play-developer-mcp)
[![npm downloads](https://img.shields.io/npm/dm/google-play-developer-mcp.svg)](https://www.npmjs.com/package/google-play-developer-mcp)
[![CI](https://github.com/devinwang/google-play-developer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/devinwang/google-play-developer-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](package.json)
[![Tools: 157](https://img.shields.io/badge/tools-157-informational.svg)](#feature-matrix)
[![API: v3](https://img.shields.io/badge/Android%20Publisher-v3-4285F4.svg)](https://developers.google.com/android-publisher/api-ref/rest)
[![Reporting: v1beta1](https://img.shields.io/badge/Play%20Reporting-v1beta1-4285F4.svg)](https://developers.google.com/play/developer/reporting)
[![MCP](https://img.shields.io/badge/MCP-compatible-9B59B6.svg)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg)](tsconfig.json)

**See also:** [`app-store-connect-mcp`](https://github.com/devinwang/app-store-connect-mcp) — the same philosophy for Apple's App Store Connect.

---

## Table of Contents

- [Why this exists](#why-this-exists)
- [Feature matrix](#feature-matrix)
- [Quick start](#quick-start)
- [Step-by-step setup](#step-by-step-setup)
- [Register with your MCP client](#register-with-your-mcp-client)
- [Usage examples](#usage-examples)
- [Tool reference](#tool-reference)
- [Security](#security)
- [Design notes](#design-notes)
- [Contributing](#contributing)
- [Version history](#version-history)
- [References](#references)

---

## Why this exists

Google Play Console has an API, but its surface is wide and moves fast. Existing community MCPs each cover a slice — one does store listings, another does releases, a third does reviews — and all lag behind Google's deprecations.

**`google-play-developer-mcp` is the one that covers everything.**

| Property | This server | Typical community MCP |
|---|---|---|
| Android Publisher API v3 | ✅ Full | Partial |
| Play Developer Reporting API | ✅ Full | ❌ Missing |
| `monetization.onetimeproducts` (post-2025 catalog) | ✅ | Uses deprecated `inappproducts` |
| `purchases.subscriptionsv2` / `productsv2` | ✅ | Often still on v1 |
| 2026 features (OfferPhase, cancel/defer, priceStepUp) | ✅ | ❌ |
| Multi-account | ✅ | Usually one |
| Credential safety | No keys in repo, strict `.gitignore` | Varies |
| Public release under semver | ✅ v1.0.0 | Mostly pre-1.0 |

If you drive Google Play Console with an AI assistant — release automation, review triage, subscription catalog management, crash triage — this gives the assistant a full toolbox in one install.

---

## Feature matrix

**157 tools across 33 groups. Every non-deprecated endpoint in both APIs.**

<details open>
<summary><strong>Android Publisher API v3</strong></summary>

| Group | Tools | Covers |
|---|---|---|
| `accounts_*` | 6 | Local registry — add / list / switch / remove / update multiple Play Console accounts |
| `auth_*` | 1 | Verify the service account can acquire a token |
| `apps_*` | 2 | List every app the service account can see, get app details |
| `edits_*` | 5 | Managed-publishing transactions: `insert`, `get`, `validate`, `commit`, `delete` |
| `details_*` | 3 | App-level contact email / phone / website, default language |
| `country_availability_*` | 1 | Per-country availability within an edit |
| `listings_*` | 6 | Per-locale title / short description / full description / video. Includes `delete_all` |
| `images_*` | 4 | Icon, feature graphic, promo graphic, phone/tablet/TV/wear screenshots. List, upload, delete, delete-all |
| `bundles_*` | 2 | Upload and list Android App Bundles (AAB) |
| `apks_*` | 3 | Upload / list APKs + register externally-hosted APK (enterprise) |
| `deobfuscation_files_*` | 1 | Upload ProGuard / native code mapping |
| `expansion_files_*` | 4 | OBB — get / upload / update / patch |
| `tracks_*` | 5 | `internal`, `alpha`, `beta`, `production`, plus custom closed-testing tracks. List, get, update, patch, create |
| `testers_*` | 3 | Google Groups allowlists for internal / closed tracks |
| `onetime_products_*` | 17 | ✨ New monetization catalog for non-subscription products. Three-level hierarchy: product → purchase option → offer. Complete CRUD + batch on all three levels |
| `subscriptions_*` | 8 | Subscription catalog: list, create, update, delete, archive, batch-get, batch-update |
| `subscription_base_plans_*` | 7 | Monthly/annual plans. Activate, deactivate, migrate prices, batch migrate, batch update + states |
| `subscription_offers_*` | 10 | Free trials / introductory prices. Create, update, delete, activate, deactivate + batch flavours |
| `monetization_convert_region_prices` | 1 | Compute comparable region prices from one input price |
| `purchases_products_v2_*` | 1 | Verify one-time-product purchases (supports multiple purchase options + offers) |
| `purchases_products_*` | 2 | Acknowledge / consume one-time purchases (`productsv2` only exposes `get`) |
| `purchases_subscriptions_v2_*` | 4 | Get, revoke, cancel, defer. Includes 2026 `OfferPhase`, `outOfAppPurchaseContext`, priceStepUp consent, item-based refund |
| `purchases_subscriptions_acknowledge` | 1 | v1 acknowledge (retained — still the right call for acknowledging initial purchase) |
| `purchases_voided_list` | 1 | Refund / chargeback feed |
| `orders_*` | 5 | List, get, batch-get, refund, review refund (get + batch-get added 2025-05, `review_refund` added 2026-07 for collaborative chargebacks) |
| `external_transactions_*` | 3 | Alternative Billing (Korea / EU) — get / create / refund |
| `reviews_*` | 3 | List, get, reply |
| `users_*` + `grants_*` | 7 | Team members & per-app grants |
| `device_tier_configs_*` | 3 | Device-tier targeting for AAB |
| `app_recovery_*` | 5 | Recovery actions: list, create, deploy, cancel, add targeting |
| `generated_apks_*` | 2 | List and download generated APKs from an AAB |
| `system_apks_variants_*` | 4 | System APK variants for preload scenarios |
| `internal_app_sharing_*` | 2 | Upload APK or AAB for internal link sharing |

</details>

<details open>
<summary><strong>Play Developer Reporting API v1beta1</strong></summary>

| Group | Tools | Covers |
|---|---|---|
| `reports_apps_*` | 2 | `search`, `fetch_release_filter_options` |
| `reports_anomalies_list` | 1 | Detected anomalies across all metric sets |
| `reports_crash_rate_*` | 2 | Crash rate — metadata + time-series query |
| `reports_anr_rate_*` | 2 | ANR rate |
| `reports_slow_start_rate_*` | 2 | Slow start (cold launch) |
| `reports_slow_rendering_rate_*` | 2 | Slow rendering (jank) |
| `reports_excessive_wakeup_rate_*` | 2 | Battery — excessive wake-ups |
| `reports_stuck_background_wake_lock_rate_*` | 2 | Battery — stuck wake locks |
| `reports_lmk_rate_*` | 2 | Low-memory killer rate |
| `reports_anon_rss_swap_memory_*` | 2 | Anonymous RSS + swap memory usage |
| `reports_bitmap_memory_*` | 2 | Bitmap memory usage |
| `reports_errors_counts_*` | 2 | Aggregate error counts |
| `reports_errors_issues_search` | 1 | Grouped ErrorIssue search |
| `reports_errors_reports_search` | 1 | Raw ErrorReport search |

</details>

---

## Quick start

```bash
npm install -g google-play-developer-mcp
```

Then in your MCP client config (e.g. `~/.config/claude/config.json`, Cursor MCP config, or VS Code `mcp.json`):

```json
{
  "mcpServers": {
    "google-play-developer": {
      "command": "google-play-developer-mcp"
    }
  }
}
```

Next, tell the server which Play Console account to use — see the [setup guide](#step-by-step-setup) below.

---

## Step-by-step setup

### 1. Create a Google Cloud service account

1. Open the [Google Cloud Console](https://console.cloud.google.com/).
2. Select or create a project (any project — this is just where the service account lives).
3. **APIs & Services → Library** — enable both of these:
   - **Google Play Android Developer API**
   - **Google Play Developer Reporting API**
4. **IAM & Admin → Service Accounts → Create service account**.
5. Once created, open the account → **Keys → Add key → JSON**. Download the JSON file.
6. Move the JSON file somewhere safe and outside any git repo. A good location: `~/.config/google-play-developer-mcp/service-account.json`.

### 2. Authorize the service account in Play Console

1. Open [Play Console](https://play.google.com/console).
2. **Users and permissions → Invite new user**. Paste the service account email (it looks like `name@project-id.iam.gserviceaccount.com`).
3. Assign permissions:
   - **Admin (all permissions)** for full access.
   - Or narrower combinations (View app information, Manage store presence, Manage orders and subscriptions, etc.) if you want to restrict what the MCP can do.
4. **Wait up to 24 hours.** Play Console takes time to propagate the new authorization — this is a common gotcha. If early API calls return `PERMISSION_DENIED`, this is usually why.

### 3. Register the account with the MCP server

Launch any MCP client that has the server configured, then run:

```
accounts_add --name my-app \
  --keyFile /Users/you/.config/google-play-developer-mcp/service-account.json \
  --description "My company's Play Console"
```

(Or manually create `~/.google-play-developer-mcp/accounts.json` — see the file format below.)

### 4. Verify

```
auth_status
```

Should return `{ ok: true, email: "..." }`.

```
apps_list
```

Lists the apps the service account can see.

---

## Register with yo