# google-cloud-console-mcp

An MCP server that gives AI assistants (Claude, etc.) hands-on control of **Google Play Console**
and **Google Cloud Console** through a Google identity you authorize — a service account, or your
own Google account via a one-time browser sign-in.

95 tools across four domains:

- **Play Console** (`play_*`) — apps, edits, uploading new AAB/APK builds, managing release
  tracks (internal/alpha/beta/production, staged rollouts, pulling a bad version), store listings
  & screenshots, replying to reviews, in-app products & subscriptions, testers.
- **Cloud Console core** (`gcp_*`) — Resource Manager (projects, IAM policy), IAM (service
  accounts, keys), Service Usage (enable/disable APIs).
- **Firebase** (`firebase_*`) — project/app management, App Distribution (upload builds to
  testers, manage tester groups).
- **Storage** (`gcs_*`, `ar_*`) — Cloud Storage buckets/objects, Artifact Registry repositories.

See [`docs/TOOLS.md`](docs/TOOLS.md) for the full list with descriptions.

## Quickstart

Pick a credential mode, then register the server with Claude Code. Full walkthrough (including
the required manual Play Console linking step) is in [`docs/SETUP.md`](docs/SETUP.md).

**Service account:**
```bash
./scripts/setup-gcp.sh your-project-id     # or scripts\setup-gcp.ps1 on Windows

claude mcp add google-cloud-console \
  -e GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/credentials/service-account.json" \
  -e GOOGLE_CLOUD_PROJECT="your-project-id" \
  -- npx -y google-cloud-console-mcp
```

**Sign in with your Google account (browser OAuth):**
```bash
export GOOGLE_OAUTH_CLIENT_ID=xxxxx.apps.googleusercontent.com
export GOOGLE_OAUTH_CLIENT_SECRET=xxxxx
npx -y google-cloud-console-mcp login      # opens a browser once

claude mcp add google-cloud-console -- npx -y google-cloud-console-mcp
```

**Sign in from Claude Code's native `/mcp` screen instead** (no `login` step, but you run the
server yourself over HTTP — see [`docs/SETUP.md` Path C](docs/SETUP.md#path-c--native-mcp-authentication-in-claude-code-http-transport)):
```bash
export GOOGLE_OAUTH_CLIENT_ID=xxxxx.apps.googleusercontent.com
export GOOGLE_OAUTH_CLIENT_SECRET=xxxxx
npx -y google-cloud-console-mcp --http --port 3939   # keep this running

claude mcp add google-cloud-console --transport http http://127.0.0.1:3939/mcp
# then run /mcp in Claude Code and authenticate when prompted
```

> **Not published to npm yet?** `npx -y google-cloud-console-mcp` only works once this package is
> published. Until then, run `npm run build` here and point `claude mcp add` at the built file
> directly instead of `-- npx -y google-cloud-console-mcp`:
> ```
> claude mcp add google-cloud-console -e GOOGLE_APPLICATION_CREDENTIALS="..." -- node /path/to/google-cloud-console-mcp/dist/index.js
> ```

Then ask Claude to do something read-only first — "list my GCP projects", "list release tracks
for com.example.app" — to confirm credentials are wired up before trying anything that writes.

## Using it with Claude Desktop instead

Add the block from [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)
to your Claude Desktop config (`claude_desktop_config.json`), filling in your own credential
values.

## How auth is resolved

In HTTP mode (`--http`, Path C), each request carries its own verified Google access token
(from Claude Code's native `/mcp` OAuth sign-in) and that's used directly.

Otherwise (stdio mode, the default), the server picks the first of these that's available (see
`src/auth/googleAuth.ts`):
1. `GOOGLE_SERVICE_ACCOUNT_JSON` — service account key JSON, inline
2. `GOOGLE_APPLICATION_CREDENTIALS` — path to a service account key file
3. A token saved by `google-cloud-console-mcp login` (OAuth)
4. Standard Application Default Credentials discovery (`gcloud auth application-default login`,
   or the GCE/Cloud Run metadata server when actually running on GCP infra)

## Narrowing exposure

By default every tool group is registered. To limit which ones are available (least privilege for
what you're using it for right now), set:
```bash
GOOGLE_MCP_TOOL_GROUPS=playconsole,cloudcore
```
Valid group names: `playconsole`, `cloudcore`, `firebase`, `storage`.

## Development

```bash
npm install
npm run build        # tsc -> dist/
npm test             # vitest
npm run typecheck
npm run dev           # tsx watch, runs src/index.ts directly (no build step)
npm run gen:tools-doc # regenerate docs/TOOLS.md from the live tool registry
```

Project layout:
```
src/
  auth/           credential resolution, OAuth login flow, and the HTTP-mode OAuth bridge
                  (oauthBridgeProvider.ts — bridges Claude Code's native `/mcp` OAuth to Google)
  lib/            shared helpers (tool definition, error formatting, logging, per-request auth context)
  tools/
    playconsole/  Android Publisher API tools
    cloudcore/    Resource Manager, IAM, Service Usage tools
    firebase/     Firebase project/app + App Distribution tools
    storage/      Cloud Storage + Artifact Registry tools
  server.ts       builds the McpServer + registers every tool (shared by stdio and HTTP)
  httpServer.ts   HTTP transport + OAuth endpoints for Path C (`--http`)
  index.ts        CLI entrypoint (login/logout/whoami/--http/serve)
```

Adding a tool: pick the right `src/tools/<domain>/*.ts` file, add a `defineTool({...})` call, add
it to that file's exported array. It's picked up automatically — no registry to edit by hand.

## Security

This server can be granted very broad access on purpose — that's the point. Scope what you grant
it (IAM roles, Play Console permissions, `GOOGLE_MCP_TOOL_GROUPS`) to what you actually want an AI
assistant able to do unattended, and see the security notes in `docs/SETUP.md`. Never commit
`credentials/` or `.env`.

## License

MIT — see [`LICENSE`](LICENSE).