Google Play Vitals MCP Server

English | 简体中文

Google Play Vitals MCP is a high-performance, token-efficient Model Context Protocol (MCP) server for the Google Play Developer Reporting API (Android Vitals).

Designed specifically for AI coding assistants and autonomous agents (Cursor, Claude Desktop, Claude Code, Codex, Windsurf, and Cline), it empowers AI to analyze Android production stability, diagnose ANRs (Application Not Responding), track crash trends, and verify startup optimizations (such as AndroidX Baseline Profiles) with minimal context token consumption.

🌟 Key Highlights

• Token Economy by Design (Token Saver): Upstream Google Developer Reporting APIs return deeply nested, verbose Protobuf responses. Our built-in compression engine strips 80%+ redundant metadata and automatically reassembles raw frame data into clean, single-line standard Java stack traces (at com.example.Foo.bar(Foo.java:42)).
• One-Shot Comprehensive Diagnosis (play_get_top_anr_summary): Eliminates the frustration of multi-turn tool roundtrips. A single tool call aggregates Top ANR clusters, affected user counts, occurrence numbers, and their representative de-obfuscated main thread stack traces.
• Version Comparative Analysis (play_compare_versions): Specifically designed for quantifying release optimizations. Compare before-and-after versions (e.g., verifying ANR governance or Baseline Profile cold-start acceleration) with automated delta calculation and percentage improvement reporting.
• Universal & Production Decoupled: Zero proprietary hardcoding. Supports any Android package, dynamic runtime parameters, environment variables, Service Account JSON files, JSON strings, or Google Application Default Credentials (ADC).
• Zero-Latency In-Memory Hot Cache: Built-in 5-minute LRU cache prevents accidental quota exhaustion during multi-step AI reasoning.
• Broad Agent Compatibility: Works out of the box with Cursor, Claude Desktop, Claude Code, Windsurf, Codex, and standard MCP JSON-RPC 2.0 stdio clients.

🛠️ MCP Tools Overview

1. Atomic Core Tools (Recommended for Autonomous Agents)

2. Analytics & Convenience Tools

📝 MCP Prompts & Resources

🚀 Quick Start

1. Installation

Option A: Install via pip or uv

pip install google-play-vitals-mcp
# or
uv pip install google-play-vitals-mcp

Option B: One-click Install via Smithery (Cursor / Windsurf / Claude)

npx -y @smithery/cli install google-play-vitals-mcp --client cursor

Option C: Docker Container

docker run -i --rm -v ~/.config/gcp:/gcp -e GOOGLE_APPLICATION_CREDENTIALS=/gcp/key.json google-play-vitals-mcp

2. Authentication & Credentials

Google Play Developer Reporting API requires enterprise authentication via a Google Cloud Service Account authorized with "View app quality data" read-only permission:

Option A: Google Cloud Service Account JSON Key (Standard)

1. Ask your Google Play Console administrator (Account Owner) for a Service Account JSON key with "View app quality data" read-only permission.
2. Set the environment variable:

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/play_service_account.json"
   

Option B: CI/CD Plaintext JSON

export GOOGLE_PLAY_CREDENTIALS_JSON='{"type": "service_account", "project_id": "..."}'

🤖 AI Client Integration Guides

1. Cursor

Add to your project's .cursor/mcp.json or global Cursor settings:

{
  "mcpServers": {
    "google-play-vitals": {
      "command": "google-play-vitals-mcp",
      "args": [],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/play_service_account.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.yourcompany.app"
      }
    }
  }
}

Note: You can also run with python -m google_play_vitals_mcp if installed in a specific virtual environment.

2. Claude Desktop

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-play-vitals": {
      "command": "google-play-vitals-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/play_service_account.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.yourcompany.app"
      }
    }
  }
}

3. Claude Code CLI

Add the MCP server directly via CLI:

claude mcp add google-play-vitals -- \
  google-play-vitals-mcp \
  --package-name com.yourcompany.app \
  --credentials /path/to/play_service_account.json

4. Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "google-play-vitals": {
      "command": "google-play-vitals-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/play_service_account.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.yourcompany.app"
      }
    }
  }
}

💡 Prompt Examples

Once configured, simply talk to your AI assistant:

• "Find the top 10 Crashes and ANRs for our latest production release, along with de-obfuscated stack traces."
• "Check Google Play Vitals connection status."
• "Analyze the top ANR clusters in production right now and show me the problematic stack traces."
• "Show me the daily ANR rate and slow startup rate for the last 14 days."
• "Compare version 204000 against version 203000 to verify if our Baseline Profile and ANR fixes improved cold startup and reduced ANRs."
• "Inspect issue apps/com.example/errorIssues/123456 and retrieve the raw device reports."

💻 CLI Commands

The package includes a built-in CLI:

# Check configuration and credentials readiness
google-play-vitals-mcp check -p com.example.app -c /path/to/key.json

# Launch MCP stdio server manually
google-play-vitals-mcp run -p com.example.app

# Check version
google-play-vitals-mcp --version

🔧 Environment Variables

🧪 Development & Testing

# Clone repository
git clone https://github.com/OldJii/google-play-vitals-mcp.git
cd google-play-vitals-mcp

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest -v

# Run linting
ruff check .
ruff format --check .

📄 License

This project is licensed under the MIT License.