Play Store MCP Server

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.

📖 Full Documentation

✨ 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

🚀 Quick Start

Prerequisites

Google Cloud Project with the Google Play Developer API enabled
Service Account with access to your Play Console
Python 3.11+, uvx, or Docker installed

Installation

Using uvx (Recommended)

# Run directly without installation
uvx play-store-mcp

Using pip

pip install play-store-mcp
play-store-mcp

Using Docker

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

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:

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:

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:

{
  "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:

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:

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.

play-store-mcp --read-only
# or
export PLAY_STORE_MCP_READ_ONLY=1

Code Mode (Experimental)

Opt in to the experimental code-mode transform to serve the tools as three meta-tools (search/get_schema/execute) instead of the full tool list, cutting per-request tool-list token overhead. It is off by default. Install the sandbox extra and set the environment variable (CODE_MODE is env-only — there is no CLI flag):

pip install "play-store-mcp[code-mode]"
export CODE_MODE=1

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:

{
  "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:

{
  "mcpServers": {
    "play-store": {
      "command": "uvx",
      "args": ["play-store-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Gemini CLI / Other MCP Clients

{
  "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.)

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

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Play Developer API
Go to IAM & Admin > Service Accounts
Create a new service account
Download the JSON key file

2. Grant Play Console Access

Go to Google Play Console
Navigate to Users and permissions
Click Invite new users
Enter the service account email (from the JSON file)
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 for `stdio` (defaults to cwd); required for network transports
`CODE_MODE`	Enable the experimental code-mode transform (opt-in; requires the `play-store-mcp[code-mode]` extra)	No (default: off)

🧪 Development

Setup

git clone https://github.com/lusky3/play-store-mcp.git
cd play-store-mcp
uv sync --dev

Running Tests

uv run pytest -v --cov=src/play_store_mcp

Linting

ruff check src/ tests/
ruff format src/ tests/

Type Checking

mypy src/

🐛 Troubleshooting

Error: "Service account key not found"

Ensure GOOGLE_APPLICATION_CREDENTIALS points to a valid JSON file:

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

🙏 Acknowledgments

Inspired by antoniolg/play-store-mcp (Kotlin)
Built with the MCP Python SDK
Uses the Google Play Developer API

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

Name		Name	Last commit message	Last commit date
Latest commit History 173 Commits
.github		.github
.qlty		.qlty
docs		docs
examples		examples
src/play_store_mcp		src/play_store_mcp
tests		tests
wiki @ 965f168		wiki @ 965f168
.codacy.yaml		.codacy.yaml
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
FEATURE_SUMMARY.md		FEATURE_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation