google-play-analytics-mcp

An MCP server that exposes Google Play Console analytics to AI agents — store-listing acquisitions by traffic source (Explore / Search / Ads & referrals), installs & uninstalls, ratings, crashes, subscriptions and reviews.

It reads the bulk CSV reports that Google Play Console automatically exports to your developer Cloud Storage bucket (pubsite_prod_rev_*), using a Google Cloud service account (fully non-interactive — no browser login, no token refresh dance). Reports are monthly files of daily rows; the server discovers, downloads, decodes, parses and aggregates them behind a small set of tools.

Play Console publishes these reports with a lag of ~1–2 days, so the freshest data is usually yesterday or the day before.

Why this exists

The Play Console UI shows acquisition data (how many people found your app by browsing vs searching the Play Store, and how well your store listing converts visitors to installers), but there's no convenient API for an agent to read it. The underlying data, however, is exported as CSV to a Cloud Storage bucket. This server turns that bucket into typed, queryable tools — the Android counterpart to Apple's "App Store Browse vs Search" source-type analytics.

Related MCP server: play-store-mcp

Tools

Common parameters: package (an alias or a full package name), start_date / end_date (ISO YYYY-MM-DD, default = last 30 days), and per-tool dimension, daily, top.

Report families & data coverage

cancellations quirks: the file is a ZIP archive under a .csv name (unpacked automatically), holds the package's entire history and is rewritten daily. It carries only the free-text answers from Play's cancel survey — the multiple-choice reason counts are not in the bulk export. Google writes nearly every answer 3 times (sometimes with Country on one copy only); get_cancellation_reasons collapses them on date + SKU + answer. The same answer can reappear ~3 days later (likely one user at trial cancel and at expiry) — that is not merged. Country is blank on most rows.

Google discontinued the retained_installers and buyers_7d bulk exports after June 2021 (and ratings_v2 was a short-lived 2022–2023 schema). Their store-listing conversion rate was replaced by the current store_conversion family (visitors + CVR); acquisitions live in store_performance. The historical families remain queryable for backfill.

Prerequisites

1. A Google Play Console account with reports being exported to a Cloud Storage bucket (this is on by default; the bucket is pubsite_prod_rev_<number>).

2. A Google Cloud service account with read access to that bucket, plus its JSON key. Two ways to grant access:

   • Play Console link (recommended): Play Console → Users and permissions → invite the service-account email → grant View app information and download bulk reports; or

   • Bucket IAM: grant the service account roles/storage.objectViewer on the pubsite_prod_rev_* bucket in the Google Cloud console.

3. Python 3.11+.

Install

git clone git@github.com:desunit/google-play-analytics-mcp.git
cd google-play-analytics-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Configure

The server is configured entirely through environment variables (no secrets in the repo):

* If GOOGLE_PLAY_SA_JSON is unset, the server also looks for google-play.json in ~/.config/google-play-analytics-mcp/ or next to server.py. Never commit the key — it's gitignored.

Finding your bucket name: Play Console → Download reports → open any report category → Copy Cloud Storage URI. The bucket is the part between gs:// and the first /.

App aliases (optional): copy apps.example.json → apps.json (gitignored) to map short names like my-app to package names, or set GOOGLE_PLAY_APP_ALIASES. Full package names always work without aliases.

Register with your MCP client

Copy .mcp.json.example and fill in absolute paths, or add to your client config:

{
  "mcpServers": {
    "google-play-analytics": {
      "command": "/abs/path/google-play-analytics-mcp/.venv/bin/python",
      "args": ["/abs/path/google-play-analytics-mcp/server.py"],
      "env": {
        "GOOGLE_PLAY_SA_JSON": "/abs/path/service-account.json",
        "GOOGLE_PLAY_REPORTS_BUCKET": "pubsite_prod_rev_XXXXXXXXXXXXXXXX"
      }
    }
  }
}

For Claude Code, the equivalent one-liner:

claude mcp add google-play-analytics \
  -e GOOGLE_PLAY_SA_JSON=/abs/path/service-account.json \
  -e GOOGLE_PLAY_REPORTS_BUCKET=pubsite_prod_rev_XXXXXXXXXXXXXXXX \
  -- /abs/path/.venv/bin/python /abs/path/server.py

Verify

export GOOGLE_PLAY_SA_JSON=/abs/path/service-account.json
export GOOGLE_PLAY_REPORTS_BUCKET=pubsite_prod_rev_XXXXXXXXXXXXXXXX
./.venv/bin/python -c "import server, json; print(json.dumps(server.health_check(), indent=2))"

A healthy response lists your bucket's top-level prefixes (acquisition/, stats/, financial-stats/, reviews/, …).

Example questions it answers

• "What share of my Play Store installs come from browsing (Explore) vs Search?" → get_acquisitions_by_traffic_source

• "Which countries drive the most store acquisitions this month?" → get_acquisitions_by_country

• "Which Google Play search terms bring visitors, and which convert best?" → get_search_terms (branded terms typically convert far higher than generic ones)

• "Which UTM campaigns and sources drive store installs?" → get_utm_performance (e.g. <source> / <campaign>)

• "What's my visitor→install conversion rate by country?" → get_store_conversion(dimension="country")

• "How do installs break down by language?" → get_installs(dimension="language")

• "What's my daily install and uninstall trend?" → get_installs(daily=True)

• "How is my rating trending?" → get_ratings

• "Which app versions crash most?" → get_crashes(dimension="app_version")

How it works

service account key ──► google-auth ──► short-lived Storage token
                                             │
        GCS JSON API: list + download objects under pubsite_prod_rev_*
                                             │
     BOM-aware decode (UTF-16 / UTF-8) ──► CSV parse ──► date-filter ──► aggregate

Downloaded report files are cached under GOOGLE_PLAY_CACHE_DIR so repeat queries don't re-fetch. Object listings are cached per process.

Cache validation (important)

Play rewrites the current month's report file every day as new days land. A cache that is never revalidated therefore serves a truncated month — the data looks complete, it just silently stops days or weeks early.

Every cached file is validated on read against the object's bucket-side updated + size, plus the on-disk byte length recorded when it was written. Any mismatch re-downloads. Use clear_report_cache(pattern=...) only to drop a suspected-corrupt entry; routine use is unnecessary.

Coverage (important)

Every response carries a coverage block:

"coverage": {
  "data_through": "2026-07-21", "requested_through": "2026-07-23",
  "days_expected": 7, "days_present": 4,
  "missing_dates": ["2026-07-20", "2026-07-22", "2026-07-23"],
  "lag_days": 2,
  "warning": "1 day(s) missing INSIDE the range (2026-07-20) — per-day averages, not sums, are needed to compare this window with another."
}

Play publishes with a lag and occasionally drops a day mid-range. Read coverage before comparing two windows — otherwise a "7-day vs 7-day" comparison can silently be 7 days against 4, which reads as a ~40% decline that is not real. When days_present differs between windows, compare per-day means.

Security

• No credentials are stored in this repository. The service-account key, the bucket name and any app aliases are all supplied at runtime via env vars or gitignored local files (google-play.json, apps.json).

• The service account only needs read-only Storage scope (devstorage.read_only). This server never writes to your bucket or Play Console.

• Downloaded reports (which contain your business data) are cached outside the repo tree by default (~/.cache/...).

Author

Built by Songtive — @desunit on X.

License

MIT © Songtive