Play Store MCP Server
by beshoo
README.md
# Play Store MCP Server
[](https://github.com/lusky3/play-store-mcp/actions/workflows/ci.yml)
[](https://codecov.io/github/lusky3/play-store-mcp)
[](https://sonarcloud.io/summary/new_code?id=lusky3_play-store-mcp)
[](https://sonarcloud.io/summary/new_code?id=lusky3_play-store-mcp)
[](https://sonarcloud.io/summary/new_code?id=lusky3_play-store-mcp)
[](https://sonarcloud.io/summary/new_code?id=lusky3_play-store-mcp)
[](https://badge.fury.io/py/play-store-mcp)
[](https://github.com/lusky3/play-store-mcp/pkgs/container/play-store-mcp)
[](https://www.python.org/downloads/)
[](https://sonarcloud.io/summary/new_code?id=lusky3_play-store-mcp)
[](https://opensource.org/licenses/MIT)
[](https://glama.ai/mcp/servers/lusky3/play-store-mcp)
An MCP (Model Context Protocol) server that connects to the Google Play Developer API. Deploy apps, manage releases, respond to reviews, and monitor app health โ all through your AI assistant.
> **About this fork.** This is a fork of
> [lusky3/play-store-mcp](https://github.com/lusky3/play-store-mcp) that adds
> high-level workflows, several modeled on
> [Jang-myoung-gyoon/google-play-mcp](https://github.com/Jang-myoung-gyoon/google-play-mcp):
> one-price **regional pricing** for in-app products and subscriptions,
> **all-or-nothing image replacement**, **whole-listing sync from a
> fastlane-style folder**, and automatic handling of **draft apps** and
> **"changes not sent for review"** commits. See
> [Workflow Tools](#workflow-tools-this-fork) below.
๐ **[Full Documentation](https://lusky3.github.io/play-store-mcp)**
## โจ Features
- ๐ **App Deployment** โ Deploy APK/AAB files to any track (internal, alpha, beta, production)
- โก **Batch Operations** โ Deploy to multiple tracks simultaneously
- ๐ **Multi-Language Support** โ Deploy with release notes in multiple languages
- โ
**Input Validation** โ Validate package names, tracks, and text before API calls
- ๐ **Automatic Retries** โ Built-in retry logic with exponential backoff for transient failures
- ๐ **Store Listings** โ Update app titles, descriptions, and videos for any language
- ๐ **Release Management** โ Promote releases between tracks, manage staged rollouts
- ๐ฅ **Tester Management** โ Add and manage testers for testing tracks
- โญ **Review Management** โ Fetch and reply to user reviews
- ๐ณ **Subscription Management** โ List subscriptions and check purchase status
- ๐ **In-App Products** โ List and manage in-app products
- ๐ฆ **Expansion Files** โ Manage APK expansion files for large apps
- ๐งพ **Orders** โ Retrieve detailed transaction information
- ๐ณ **Docker Support** โ Run as a container with health checks
- ๐ **Per-Request Credentials** โ Bring-your-own-credentials for multi-tenant deployments
- ๐ **Secure** โ Google Cloud service account authentication
- ๐ฒ **One-Price Regional Pricing** โ Give one price, get every region priced with Play's own conversion
- ๐ผ๏ธ **Listing Sync** โ Push titles, descriptions, icons and screenshots for every language from one folder
## ๐ Quick Start
### Prerequisites
1. **Google Cloud Project** with the Google Play Developer API enabled
2. **Service Account** with access to your Play Console
3. **Python 3.11+**, `uvx`, or **Docker** installed
### Installation
#### Using uvx (Recommended)
```bash
# Run directly without installation
uvx play-store-mcp
```
#### Using pip
```bash
pip install play-store-mcp
play-store-mcp
```
#### Using Docker
```bash
docker run -e GOOGLE_APPLICATION_CREDENTIALS=/creds/key.json \
-v /path/to/service-account.json:/creds/key.json:ro \
ghcr.io/lusky3/play-store-mcp:latest
```
#### From source
```bash
git clone https://github.com/lusky3/play-store-mcp.git
cd play-store-mcp
pip install -e .
play-store-mcp
```
### Configuration
Set the path to your service account key:
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```
### Running with HTTP Transport
For remote access or public deployments, run the server with streamable-http transport:
```bash
play-store-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
The server exposes a `/health` endpoint for monitoring.
#### Per-Request Credentials (Recommended for Public Instances)
For public deployments where users bring their own credentials, configure your MCP client to pass credentials in headers:
```json
{
"mcpServers": {
"play-store": {
"url": "https://your-server.com/mcp",
"transport": "http",
"headers": {
"X-Google-Credentials-Base64": "YOUR_BASE64_ENCODED_CREDENTIALS"
}
}
}
}
```
To get your base64-encoded credentials:
```bash
base64 -w 0 < service-account.json
```
Per-request credentials are isolated โ each request uses only the credentials provided in its headers. No credentials are stored server-side or shared between requests.
#### Server-Side Credentials (For Private/Trusted Deployments)
For private deployments, set credentials via environment variable at server startup:
```bash
export GOOGLE_PLAY_STORE_CREDENTIALS='{"type":"service_account",...}'
# or
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
play-store-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
### Read-Only Mode
To point the server at a live Play Console without any risk of mutating it, run
in read-only mode. All write tools (deploy, promote, halt, rollout, reply to
reviews, listing/tester updates) return an error instead of calling the API;
read tools are unaffected.
```bash
play-store-mcp --read-only
# or
export PLAY_STORE_MCP_READ_ONLY=1
```
### Code Mode (Experimental, enabled by default)
By default the tools are served as three meta-tools (`search`/`get_schema`/
`execute`) instead of the full tool list, cutting per-request tool-list token
overhead. The sandbox `execute` runs in is a base dependency, so this works
out of the box โ no extra install needed.
To opt out and use the classic tool list instead (`CODE_MODE` is env-only โ
there is no CLI flag):
```bash
export CODE_MODE=0
```
Under code mode one `execute` call can invoke up to 50 tool calls (including mutations) behind a single approval. Read-only enforcement still applies inside the sandbox, so pair it with `--read-only` / `PLAY_STORE_MCP_READ_ONLY=1` unless you need writes.
## ๐ง MCP Client Configuration
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"play-store": {
"command": "uvx",
"args": ["play-store-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
}
}
}
}
```
### Kiro
Add to `.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"play-store": {
"command": "uvx",
"args": ["play-store-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
}
}
}
}
```
### Gemini CLI / Other MCP Clients
```json
{
"mcpServers": {
"play-store": {
"command": "uvx",
"args": ["play-store-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
}
}
}
}
```
## ๐ ๏ธ Available Tools
### Publishing Tools
| Tool | Description |
| --- | --- |
| `deploy_app` | Deploy an APK/AAB to a track with optional staged rollout and single-language release notes |
| `deploy_app_multilang` | Deploy an APK/AAB with multi-language release notes |
| `promote_release` | Promote a release from one track to another |
| `get_releases` | Get release status for all tracks |
| `halt_release` | Halt a staged rollout |
| `update_rollout` | Update rollout percentage for a staged release |
| `get_app_details` | Get app metadata (title, description, etc.) |
### Workflow Tools (this fork)
| Tool | Description |
| --- | --- |
| `convert_region_prices` | Convert one price (e.g. `"4.99"` USD) to Play prices for every region (read-only) |
| `create_one_time_product_with_price` | Create a one-time in-app product priced in every region from one price, and activate it |
| `batch_create_one_time_products_with_price` | Create many priced one-time products; each distinct price is converted once |
| `create_subscription_with_price` | Create an auto-renewing subscription + base plan priced in every region, and activate it. Optional `free_trial` (e.g. `"P1M"`) |
| `create_free_trial_offer` | Add a free trial (e.g. 1 month free, then the normal price) to an existing subscription base plan |
| `replace_listing_images` | Upload several screenshots/icon/feature graphic for one language in a single all-or-nothing commit |
| `sync_listing_from_directory` | Sync listing text and images for every language from a fastlane-style folder (supports `dry_run`) |
`deploy_app` and `promote_release` also gained:
- **Draft-app handling** โ an app that has never been published only accepts
`draft` releases. The release is retried as a draft automatically, so the
first upload of a new app works.
- **`release_status`** on `deploy_app` โ pass `"draft"` to stage a release
without rolling it out. A status that contradicts `rollout_percentage`
(e.g. `completed` with a 5% rollout) is rejected.
- **Review fallback** โ for deploys, promotions, image replacement and listing
sync, when Play refuses to send changes for review automatically the commit
is retried with `changesNotSentForReview=true` and the result tells you to
send them for review from the Play Console. Other tools still report the
error.
#### Listing folder layout
`sync_listing_from_directory` reads the same layout as fastlane `supply`, so
existing `fastlane/metadata/android` folders work unchanged:
```text
metadata/
โโโ en-US/
โ โโโ title.txt # max 30 chars
โ โโโ short_description.txt # max 80 chars
โ โโโ full_description.txt # max 4000 chars
โ โโโ video.txt # optional YouTube URL
โ โโโ images/
โ โโโ icon.png # 512x512
โ โโโ featureGraphic.png # 1024x500
โ โโโ phoneScreenshots/ # 1.png, 2.png, ... (up to 8, natural sort order)
โ โโโ sevenInchScreenshots/
โ โโโ tenInchScreenshots/
โโโ de-DE/
โโโ ...
```
Only what exists in the folder is changed. Everything is validated first and
applied in one commit; use `dry_run=true` to preview.
#### Example prompts
- *"Create a consumable `coins_500` called '500 Coins' for $1.99 in com.example.app."*
- *"Create a monthly subscription `premium` at $4.99 with benefits 'No ads' and 'Cloud sync'."*
- *"Create a monthly subscription `premium` at $4.99 with the first month free for new customers."*
- *"Add a 7-day free trial to the `monthly` plan of `premium`."*
- *"Dry-run a listing sync from ./fastlane/metadata/android, then apply it."*
- *"Replace the en-US phone screenshots with the PNGs in ./shots."*
### Store Listings Tools
| Tool | Description |
| --- | --- |
| `get_listing` | Get store listing for a specific language |
| `update_listing` | Update store listing (title, descriptions, video) |
| `list_all_listings` | List all store listings for all languages |
### Review Tools
| Tool | Description |
| --- | --- |
| `get_reviews` | Fetch recent reviews with optional filters |
| `reply_to_review` | Reply to a user review |
### Subscription Tools
| Tool | Description |
| --- | --- |
| `list_subscriptions` | List subscription products for an app |
| `get_subscription_status` | Check subscription purchase status |
| `list_voided_purchases` | List voided purchases |
### In-App Products Tools
| Tool | Description |
| --- | --- |
| `list_in_app_products` | List all in-app products for an app |
| `get_in_app_product` | Get details of a specific in-app product |
### Testers Management Tools
| Tool | Description |
| --- | --- |
| `get_testers` | Get testers for a specific testing track |
| `update_testers` | Update testers for a testing track |
### Orders Tools
| Tool | Description |
| --- | --- |
| `get_order` | Get detailed order/transaction information |
### Expansion Files Tools
| Tool | Description |
| --- | --- |
| `get_expansion_file` | Get APK expansion file information |
### Validation Tools
| Tool | Description |
| --- | --- |
| `validate_package_name` | Validate package name format |
| `validate_track` | Validate track name |
| `validate_listing_text` | Validate store listing text lengths |
### Batch Operations Tools
| Tool | Description |
| --- | --- |
| `batch_deploy` | Deploy to multiple tracks simultaneously |
## ๐ Google Cloud Setup
### 1. Create a Service Account
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Google Play Developer API**
4. Go to **IAM & Admin** > **Service Accounts**
5. Create a new service account
6. Download the JSON key file
### 2. Grant Play Console Access
1. Go to [Google Play Console](https://play.google.com/console/)
2. Navigate to **Users and permissions**
3. Click **Invite new users**
4. Enter the service account email (from the JSON file)
5. Grant the following permissions:
- **Release apps to testing tracks** (for internal/alpha/beta)
- **Release apps to production** (for production releases)
- **Reply to reviews** (for review management)
- **View app information and download bulk reports** (for app details and orders)
## ๐ Environment Variables
| Variable | Description | Required |
| --- | --- | --- |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON key | Yes (or use per-request credentials) |
| `GOOGLE_PLAY_STORE_CREDENTIALS` | Inline JSON credentials string | Alternative to file path |
| `PLAY_STORE_MCP_LOG_LEVEL` | Log level (DEBUG, INFO, WARNING, ERROR) | No (default: INFO) |
| `PLAY_STORE_MCP_DISABLE_DNS_REBINDING` | Disable DNS rebinding protection (for cloud/reverse-proxy deployments) | No |
| `PLAY_STORE_MCP_ADMIN_TOKEN` | Require `Authorization: Bearer <token>` on the `/credentials` endpoint (for deployments behind a reverse proxy) | No |
| `PLAY_STORE_MCP_READ_ONLY` | Disable all write operations (deploy, promote, rollout, reply, listing/tester updates) | No (default: off) |
| `PLAY_STORE_MCP_DOWNLOAD_DIR` | Directory that APK/AAB downloads are confined to (path-traversal / arbitrary-write protection). Downloads are always confined; defaults to the working directory when unset | No (defaults to cwd); **recommended** for network/hosted deployments โ the server warns if unset |
| `CODE_MODE` | Set to `0` to opt out of the code-mode transform and use the classic tool list | No (default: on) |
| `PLAY_STORE_MCP_IN_REVIEW_BEHAVIOR` | What a commit does when other changes are already in review: `error` refuses instead of cancelling that review; `cancel` cancels it and resubmits (Google's default) | No (default: Google's default, which cancels the in-progress review) |
## ๐งช Development
### Setup
```bash
git clone https://github.com/lusky3/play-store-mcp.git
cd play-store-mcp
uv sync --dev
```
### Running Tests
```bash
uv run pytest -v --cov=src/play_store_mcp
```
### Linting
```bash
ruff check src/ tests/
ruff format src/ tests/
```
### Type Checking
```bash
mypy src/
```
## ๐ Troubleshooting
### Error: "Service account key not found"
Ensure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid JSON file:
```bash
ls -la $GOOGLE_APPLICATION_CREDENTIALS
```
### Error: "The caller does not have permission"
Verify the service account has been granted access in Play Console with the required permissions.
### Error: "Package name not found"
Ensure the app exists in Play Console and the service account has access to it.
## ๐ License
MIT License โ see [LICENSE](LICENSE) for details.
## ๐ Acknowledgments
- Forked from [lusky3/play-store-mcp](https://github.com/lusky3/play-store-mcp) (MIT)
- Workflow ideas (regional price conversion, batch image upload, draft-app commits) from [Jang-myoung-gyoon/google-play-mcp](https://github.com/Jang-myoung-gyoon/google-play-mcp), re-implemented here
- Inspired by [antoniolg/play-store-mcp](https://github.com/antoniolg/play-store-mcp) (Kotlin)
- Built with the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Uses the [Google Play Developer API](https://developers.google.com/android-publisher)
## ๐ค AI Usage Disclaimer
Portions of this codebase were generated with the assistance of Large Language Models (LLMs). All AI-generated code has been reviewed and tested to ensure quality and correctness.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues