Play Store MCP — Python/FastMCP on Railway

Google Play MCP server with 117 original tools + 6 cloud tools, owner-password sign-in and durable JSON storage on a Railway Volume. Google account login, Redis and SQLite are not used by the server.

Google Play API access still uses your Google service-account credentials. The owner password only authorizes access to this MCP server.

Deploy on Railway

1. Create a service from this repository; Railway uses Dockerfile and railway.json.

2. Attach a Volume at /data. Run one replica and one application process. Do not run multiple Uvicorn workers.

3. Generate a public HTTPS domain.

4. Configure these variables:

Generate a password locally with openssl rand -hex 32. Do not put the actual value in source control.

MCP_SIGNING_KEY is optional: the server generates a stable private key at /data/.signing-key when it is absent. Back up the key with the Volume. Changing it invalidates portal/download tokens and makes previously encrypted job records unreadable. MCP_BEARER_TOKEN optionally supplies a separate automation token of at least 32 characters.

No Google OAuth Web client, consent screen, redirect URI, email allowlist, Redis service or SQL database is required. Railway supplies PORT automatically.

Related MCP server: playstore-release-mcp

Configure Google Play API access

Enable the Android Publisher API in the Google Cloud project, create a service account and grant it the necessary app-level permissions in Play Console. Save the downloaded service-account JSON in GOOGLE_PLAY_STORE_CREDENTIALS. Use the least privilege that covers your workflow.

Every connection authorized with the owner password can access the configured Play account and shared file library. This server uses a single-owner model.

Connect a remote MCP client

Endpoint: https://YOUR-DOMAIN/mcp. Choose OAuth in the client. On this server's consent page, enter MCP_ADMIN_PASSWORD and authorize the requested scopes. The server issues its own access/refresh tokens; it never redirects you to Google sign-in.

The protocol uses Authorization Code + PKCE S256, hashed opaque credentials, one-use codes, refresh rotation and grant revocation. Discovery is available at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

Scopes are mcp:read, mcp:write, mcp:admin and offline_access. mcp:read is required; store mutations additionally require mcp:write; updating server credentials requires mcp:admin. Global read-only mode overrides write scope. The owner page displays the client and requested permissions.

An API/CLI client can instead send Authorization: Bearer YOUR_MCP_BEARER_TOKEN when that optional token is configured. Never use the owner password or service-account JSON as a Bearer token.

Upload files and run jobs

Open /portal, sign in with the owner password and upload an AAB/APK/image. Copy the returned asset://ID and use it in original tool arguments such as file_path, apk_path, bundle_path or image_path. Chat attachments do not automatically reach the server. Uploads are chunked and resumable; the portal reports SHA-256 after completion.

For large/long operations, call:

{
  "tool_name": "deploy_app",
  "arguments": {"package_name": "com.example.app", "track": "internal", "file_path": "asset://YOUR-ID"},
  "idempotency_key": "com.example.app-internal-build-42"
}

Pass this object to start_operation, then use get_operation or list_operations to retrieve the original result. Repeating the same owner/key/arguments returns the same job. Different arguments with the same key are rejected.

Jobs persist queued, running, completed, failed or unknown status. After restart, queued work resumes and running work becomes unknown. Failed writes also become unknown conservatively. Inspect Google Play before resubmitting an uncertain operation. The queue never automatically replays a possibly committed write. Job payloads/results remain encrypted, including dates and original result fields.

The six cloud tools remain start_operation, get_operation, list_operations, list_assets, get_asset and delete_asset. The original 117 names, input schemas and read-only guards are preserved.

Storage, backups and migration

The Volume contains state.json, .signing-key (when auto-generated), lock files and assets/. JSON transactions use a thread lock, a file lock, private temporary files, fsync and atomic replacement. Corrupt state fails closed instead of silently resetting data. Back up the whole Volume privately, with its signing key.

Only one application process may own background work. Local locks do not coordinate independently deployed replicas. Keep assets and jobs off the repository and never expose Volume contents through a static web server.

Migrate an existing Redis/SQLite deployment

Stop the old service and take a private Volume backup before changing its deployment. Keep the original BRIDGE_SIGNING_KEY as MCP_SIGNING_KEY so existing encrypted job results stay readable. Remove Google Web OAuth and Redis variables after migration; the service-account JSON is still required.

Run the standalone migration in a trusted environment with the Volume mounted:

uv run python scripts/migrate_json.py --data-dir /data --adopt-owner

Inside the new Railway image, the migration is also available as python /app/migrate_json.py --data-dir /data --adopt-owner --uid 10001 when run as root. The script reads the old SQLite database without modifying it, verifies encrypted payloads, adopts assets/jobs into the single owner and writes state.json. It refuses overwrite or colliding owner/idempotency keys. The runtime refuses to silently start empty when it detects an unmigrated SQLite database. Keep the old database only as a private migration backup.

Reconnect existing MCP clients and sign in with the owner password. Old Google-backed grants and portal cookies do not carry over. Merely changing MCP_ADMIN_PASSWORD does not revoke existing server grants; use the /revoke endpoint for a grant and rotate the optional Bearer token separately when needed.

Limits and local development

See .env.example for optional file, chunk, storage and queue limits. BRIDGE_CODE_MODE=0 disables the remote code-mode endpoint. PLAY_STORE_MCP_READ_ONLY=1 blocks all 73 Google Play mutation tools while preserving file management.

uv sync --frozen --extra dev
uv run --frozen pytest -q -o addopts='' --ignore=tests/test_integration.py --ignore=tests/test_live_api.py
uv run --frozen ruff check src/ tests/ docker_entrypoint.py scripts/
uv run --frozen ruff format --check src/ tests/ docker_entrypoint.py scripts/
uv run --frozen mypy src/
uv build

Live Google tests are opt-in. The test suite exercises mocked API calls, owner OAuth, files, schema parity, durable JSON state and write guards. A passing mock test does not verify a real service account's Play permissions.

The original stdio command remains CODE_MODE=0 uv run --frozen play-store-mcp --read-only. It does not require the remote owner's password or cloud storage. See UPSTREAM_README.md for upstream/local usage.

Based on lusky3/play-store-mcp, snapshot aebcd31, under the original MIT License. The original Google API implementation and tests are retained.