# Google Play MCP

An independent, open-source MCP server for Google Play operations: publishing,
store listings, reviews, monetization, Android vitals and growth reporting.

**Early development.** The first release implements read-only release status,
reviews and bulk reports. The complete official API inventory is documented;
everything else is explicitly **Coming soon**. A method appearing in the roadmap
does not mean it is available as a tool.

[Full API catalog](docs/api-methods.md) · [Setup](docs/setup.md) ·
[Roadmap](docs/roadmap.md) · [Verification](docs/validation.md) ·
[Contributing](CONTRIBUTING.md)

## Why this project

Google Play work spans three different interfaces: the Publisher API, the
Developer Reporting API and private Cloud Storage exports. A useful assistant
needs to understand their differences. A submitted release may still be in review;
an updated CSV may contain older data; missing report rows do not mean zero users.

This project makes those distinctions explicit and keeps the entire API roadmap
visible. It is a personal project maintained by [roadhero](https://github.com/roadhero),
not an official Google product. An open-source core comes first; hosted services
may be considered later. There is no hosted service or paid plan today.

## Available now

| Tool | What it does |
| --- | --- |
| `list_api_methods` | Search every method in the pinned official definitions, with implementation status and pagination. Works without credentials. |
| `list_releases` | Read release lifecycle states for a production, testing or custom track without opening a publishing edit. |
| `list_reviews` | Read recent written reviews with pagination and optional translation. |
| `get_review` | Read one review by ID. |
| `list_report_files` | Discover monthly installs, ratings and store-performance CSVs for a configured app. |
| `read_report` | Read an exact CSV generation with original metric names, explicit date coverage and row pagination. |

The catalog covers **145 Android Publisher v3 methods and 25 Play Developer
Reporting v1beta1 methods** from discovery revision `20261001`, plus two supporting
Cloud Storage methods. Three Publisher methods and the two scoped Storage
operations are implemented. All 25 Reporting methods and the remaining 142
Publisher methods are coming soon. [See every method and its status](docs/api-methods.md).

## Quick start

Requires Python 3.11+, [uv](https://docs.astral.sh/uv/), and macOS or Linux.
No PyPI release has been published; install from a reviewed checkout:

```bash
git clone https://github.com/roadhero/google-play-mcp.git
cd google-play-mcp
uv sync --frozen
uv run --frozen google-play-mcp
```

The last command starts an MCP **stdio** server and waits for its client. It does
not open a web page or start a background monitoring schedule. The API catalog is
available immediately; Google data requires the setup below.

### Connect with Codex

After completing [Google authentication and permissions](docs/setup.md), use
absolute paths appropriate to your computer:

```bash
codex mcp add google-play \
  --env GOOGLE_PLAY_PACKAGES=com.example.app \
  --env GOOGLE_PLAY_AUTH_MODE=gcloud \
  --env GOOGLE_PLAY_IMPERSONATE_SERVICE_ACCOUNT=play-reader@your-project.iam.gserviceaccount.com \
  --env GOOGLE_PLAY_REPORT_BUCKET=your-actual-report-bucket \
  -- /absolute/path/to/google-play-mcp/.venv/bin/google-play-mcp
```

Only set the bucket when using bulk reports; copy its exact value from Play
Console. Use the bucket name, without `gs://` or a directory suffix. Set
`GOOGLE_PLAY_GCLOUD` to the absolute CLI path if your desktop MCP host cannot find
`gcloud`. Other MCP clients can use the same executable and environment variables.

### Example requests

- “List all Google Play methods that are coming soon for subscriptions.”
- “Is version 1.2.0 actually published on production, or still in review?”
- “Read this month's store-performance report and tell me which dates are missing.”
- “Show the next page of recent written reviews.”

## Engineering boundaries

- **Read-only initial implementation:** no publish, refund, delete or permission-changing tools.
- **Explicit app allowlist:** configure package names; no default customer app.
- **Keyless authentication supported:** ADC or short-lived service-account impersonation through gcloud.
- **Secrets stay local:** credentials are not MCP arguments, committed files or tool responses.
- **Bounded reads:** timeouts, response/decompression limits, pagination and fixed API hosts.
- **No hidden redirects or writes:** the initial HTTP transport only performs GET requests.
- **Reproducible API coverage:** pinned discovery snapshots and generated-catalog drift checks.
- **Evidence-based claims:** simulated tests, real MCP interoperability and live provider checks are recorded separately.

We do not claim the entire Play Console is available through APIs. Console-only
workflows, first app creation and some policy/review actions may require manual
work. This project does not bypass those restrictions or use private Console APIs.

## Development

```bash
uv sync --frozen
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen pytest
uv run --frozen python scripts/generate_catalog.py --check
uv build
```

Tests use synthetic data by default. Production credentials are never required in
CI. See [CONTRIBUTING.md](CONTRIBUTING.md) before implementing a new method.

## License

GNU GPL v3; see the repository's existing [LICENSE](LICENSE). Official Google
discovery definitions and documentation retain their upstream notices; see
[api/README.md](api/README.md). Google Play is a Google trademark.