# 🎮 Google Play MCP Server

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-1.6-purple)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to the **Google Play Developer API v3** — enabling automated app publishing, subscription management, review monitoring, and tester management.

## ✨ Features

- **📦 Publishing** — List release tracks, upload AAB bundles, get store listings
- **💰 Subscriptions & IAP** — Query subscription products, base plans, pricing, and in-app products
- **⭐ Reviews** — List user reviews with ratings/device info, reply to reviews directly
- **👥 Testers** — Manage tester groups per release track
- **🔒 Secure** — Service account auth (server-to-server, no OAuth flow needed)
- **🤖 LLM-Optimized** — Markdown responses, clear error messages, proper `isError` flags

## 📋 Tools Reference

### Publishing

| Tool | Description | Read-only |
|------|-------------|:---------:|
| `gplay_list_tracks` | List all release tracks (internal/alpha/beta/production) with version codes, status, rollout %, and release notes | ✅ |
| `gplay_upload_bundle` | Upload `.aab` bundle → assign to track → commit. Supports draft mode and staged rollout | ❌ |
| `gplay_get_app_details` | Get store listing (title, descriptions, contact info) for any language | ✅ |

### Subscriptions & IAP

| Tool | Description | Read-only |
|------|-------------|:---------:|
| `gplay_list_subscriptions` | List all subscription products with base plans, billing periods, and pricing | ✅ |
| `gplay_get_subscription` | Get detailed subscription info including all listings, base plans, regional pricing, and offer tags | ✅ |
| `gplay_list_inapp_products` | List all one-time in-app products (consumable and non-consumable) with pricing | ✅ |

### Reviews

| Tool | Description | Read-only |
|------|-------------|:---------:|
| `gplay_list_reviews` | List user reviews with star ratings, review text, device info, app version, and developer replies. Supports translation | ✅ |
| `gplay_reply_review` | Post a developer reply to a user review (max 350 chars) | ❌ |

### Testers

| Tool | Description | Read-only |
|------|-------------|:---------:|
| `gplay_get_testers` | Get Google Group testers for a release track | ✅ |
| `gplay_update_testers` | Update tester Google Groups for a release track | ❌ |

## 🚀 Quick Start

### 1. Prerequisites

- **Node.js** ≥ 18
- A **Google Cloud** project with the [Google Play Android Developer API](https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com) enabled
- A **Service Account** with permissions granted in Play Console

### 2. Google Cloud Setup

<details>
<summary><strong>Step-by-step instructions</strong></summary>

1. **Create a Google Cloud project** (or use an existing one)
   - Go to [Google Cloud Console](https://console.cloud.google.com)

2. **Enable the API**
   - Navigate to **APIs & Services → Library**
   - Search for **Google Play Android Developer API**
   - Click **Enable**

3. **Create a Service Account**
   - Go to **IAM & Admin → Service Accounts**
   - Click **Create Service Account**
   - Give it a name (e.g., `play-console-mcp`)
   - Click **Create and Continue** → **Done**

4. **Download the JSON key**
   - Click on the service account you just created
   - Go to **Keys** tab → **Add Key → Create new key → JSON**
   - Save the downloaded file securely

5. **Grant Play Console access**
   - Go to [Google Play Console](https://play.google.com/console)
   - Navigate to **Settings → API access**
   - Link your Google Cloud project (if not already linked)
   - Find your service account and click **Manage permissions**
   - Grant the required permissions:
     - **App information** (read/write) — for store listings
     - **Release management** (read/write) — for tracks and uploads
     - **Monetization management** (read-only) — for subscriptions and IAP
     - **Reviews** (read + reply) — for review management
   - Click **Invite user** → **Send invitation**

</details>

### 3. Installation

```bash
# Clone the repository
git clone https://github.com/quan7794/google-play-mcp-server.git
cd google-play-mcp-server

# Install dependencies
npm install

# Build
npm run build
```

Or install globally via npm (once published):

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

### 4. Configuration

The server requires two environment variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `GOOGLE_SERVICE_ACCOUNT_KEY` | Absolute path to your service account JSON key file | `/home/user/.config/gcloud/play-console-key.json` |
| `GOOGLE_PLAY_PACKAGE_NAME` | Default Android package name for your app | `com.example.myapp` |

> [!NOTE]
> The `package_name` parameter can be overridden per tool call, so you can manage multiple apps with a single server instance.

### 5. Add to Your MCP Client

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "google-play": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account-key.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.example.myapp"
      }
    }
  }
}
```

</details>

<details>
<summary><strong>VS Code (Copilot / Cline / Continue)</strong></summary>

Add to your `.vscode/mcp.json` or the extension's MCP config:

```json
{
  "servers": {
    "google-play": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account-key.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.example.myapp"
      }
    }
  }
}
```

</details>

<details>
<summary><strong>Cursor</strong></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "google-play": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account-key.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.example.myapp"
      }
    }
  }
}
```

</details>

<details>
<summary><strong>Gemini CLI / Antigravity</strong></summary>

Add to `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "google-play": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account-key.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.example.myapp"
      }
    }
  }
}
```

</details>

## 💬 Usage Examples

Once connected, you can ask your AI assistant things like:

```
"Show me all release tracks and their current versions"
"Upload the bundle at ~/build/app-release.aab to internal testing"
"What subscriptions are configured for my app?"
"Show me recent 1-star reviews"
"Reply to review abc123 thanking them for the feedback"
"What testers are on the beta track?"
```

## 🔧 Development

```bash
npm run dev    # Watch mode with hot reload (tsx)
npm run build  # Compile TypeScript to dist/
npm run clean  # Remove dist/
npm start      # Run compiled server
```

### Project Structure

```
src/
├── index.ts              # Entry point — registers tools, connects stdio
├── auth.ts               # Google Auth (service account, cached client)
├── constants.ts          # Shared constants (CHARACTER_LIMIT, tracks)
├── schemas.ts            # Shared Zod schemas (PackageNameSchema)
├── tools/
│   ├── publishing.ts     # list_tracks, upload_bundle, get_app_details
│   ├── subscriptions.ts  # list/get subscriptions, list IAP
│   ├── reviews.ts        # list/reply reviews
│   └── testers.ts        # get/update testers
└── utils/
    ├── errors.ts         # GaxiosError → LLM-friendly error messages
    └── formatter.ts      # Truncation, text content helpers
```

## ❓ Troubleshooting

<details>
<summary><strong>Authentication failed (401)</strong></summary>

- Verify `GOOGLE_SERVICE_ACCOUNT_KEY` points to a valid JSON key file
- Make sure the Google Play Android Developer API is enabled in your Cloud project
- Check that the service account hasn't been deleted or disabled

</details>

<details>
<summary><strong>Permission denied (403)</strong></summary>

- Go to Play Console → **Settings → API access**
- Ensure the service account is listed and has been granted appropriate permissions
- After granting permissions, it may take a few minutes to propagate
- If you just invited the service account, make sure the invitation was accepted

</details>

<details>
<summary><strong>Resource not found (404)</strong></summary>

- Double-check `GOOGLE_PLAY_PACKAGE_NAME` matches your app's actual package name
- Make sure the app has been published at least once (even to internal testing)
- For subscription/IAP tools, ensure the products exist in Play Console

</details>

<details>
<summary><strong>Conflict error (409)</strong></summary>

- Another edit may be in progress — wait a few seconds and retry
- Edits are automatically cleaned up on failure, but a manually created edit in Play Console could conflict

</details>

## 🔒 Security

- **Service account keys** should never be committed to version control
- Use **minimal permissions** — only grant what you need
- The server runs **locally via stdio** — no network ports are opened
- All API calls use **OAuth 2.0** with the `androidpublisher` scope

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Make your changes, ensuring `npm run build` passes
4. Submit a Pull Request

### Adding a New Tool

1. Add the tool registration in the appropriate file under `src/tools/`
2. Use `withErrorHandling()` wrapper for consistent error handling
3. Use `textContent()` and `truncateIfNeeded()` for responses
4. Add proper Zod schemas with `.describe()` for all parameters
5. Set correct `annotations` (`readOnlyHint`, `destructiveHint`, etc.)
6. Update this README

## 📄 License

MIT © [Waclabs](https://github.com/quan7794)

---

Built with ❤️ using [Model Context Protocol](https://modelcontextprotocol.io) and the [Google Play Developer API v3](https://developers.google.com/android-publisher).