Setup guide

From install to your first read.

PubShip runs on your computer with your own Google credentials. This is the shortest path. Every step links to the full details on GitHub.

  • Python 3.11 or later
  • uv
  • An MCP client
  • Access to your app in Play Console

  1. Install uv

    PubShip is published on PyPI and runs with uvx, which comes with uv.

    uv installation guide
    Check that uv is available 
    uv --version

    Desktop clients can start with a different PATH from your terminal. Restart your client after installing uv.

  2. Prepare your Google access

    Use a service account you control. Grant only the access you need.

    Google access guide, including gcloud and ADC
    1. Enable the Google Play Android Developer API in your Cloud project.
    2. Create a service account, or reuse one you control.
    3. In Play Console, open Users and permissions, invite its email and grant access to your app. Read-only app information is enough to start.
    4. Save its JSON key on this computer, outside any repository, and note the absolute path.

    Never paste the key's contents into a chat, a client setting, an issue or a website. PubShip only needs the file path.

    For Android vitals, also enable the Google Play Developer Reporting API.

  3. Add PubShip to your client

    Set the key path and your app allowlist for the PubShip process. GOOGLE_PLAY_PACKAGES limits PubShip's requests; it does not change Google permissions.

    Claude Code

    First, in the shell that launches Claude Code 
    export GOOGLE_APPLICATION_CREDENTIALS=/absolute/private/path/service-account.json
export GOOGLE_PLAY_PACKAGES=com.example.app

    Add the server 
    claude mcp add --transport stdio pubship -- uvx pubship

    Documented command

    Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_PLAY_PACKAGES in the shell that launches Claude Code, then run /mcp to check the connection.

    Full instructions on GitHub

    Codex

    First, in the shell that launches Codex 
    export GOOGLE_APPLICATION_CREDENTIALS=/absolute/private/path/service-account.json
export GOOGLE_PLAY_PACKAGES=com.example.app

    Add the server 
    codex mcp add pubship -- uvx pubship
codex mcp list

    Documented command

    Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_PLAY_PACKAGES in the shell that launches Codex. Desktop apps can use a different PATH from your terminal.

    Full instructions on GitHub

    Cursor

    Service account key file
    /absolute/private/path/service-account.json
    Package names
    com.example.app

    Plugin manifest

    Not a Cursor marketplace listing. The plugin starts uvx pubship. Enter the key file path, never the key contents.

    Full instructions on GitHub

    Gemini CLI

    Add the server 
    gemini extensions install https://github.com/pubship/pubship

    Extension manifest

    Native installation not verified. Enter your key file path and package names when prompted, then restart Gemini CLI.

    Full instructions on GitHub

    Any stdio client

    MCP configuration (JSON) 
    {
  "mcpServers": {
    "pubship": {
      "command": "uvx",
      "args": ["pubship"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/private/path/service-account.json",
        "GOOGLE_PLAY_PACKAGES": "com.example.app"
      }
    }
  }
}

    Standard stdio configuration

    Command uvx, argument pubship. Keep shell syntax out of the command field.

    Full instructions on GitHub

  4. Verify, then make a first read

    The check needs no credentials and makes no Google call. It prints the PubShip name and installed version.

    Check the installation 
    uvx pubship --check

    Then confirm your client lists PubShip tools, and ask:

    Show the production releases for com.example.app. Make no changes.

    Expect a list_releases call with each release's name, version codes and lifecycle state. Waiting on Play Console access? Ask for two entries from the API catalog; it needs no credentials.

Stuck? Check these first.

Full troubleshooting table
Authentication failed
Check the key path, the selected account and any impersonation permission. Restart the client after changes.
HTTP 403
The API may be off, or the service account lacks app access in Play Console.
HTTP 429
Google's quota was reached. Retry later instead of looping.
No rows for a date
Missing rows are not zero. Check that report's coverage before filling gaps.

Where to go next

Permissions and data flowWhat PubShip can reach, and who decides.Read it → Enable changesOpt in to listing staging for one app.Listing staging on GitHub ↗ Self-host (advanced)Only for your own Google accounts, on infrastructure you control.Self-host guide on GitHub ↗