gcloud-mcp-oauth-setup
Create a Google Cloud project, enable its APIs, configure the OAuth consent screen and client, and register a remote Google MCP server (Drive, Gmail, Calendar and similar) with OAuth in Claude Code. U
SKILL.mdskills/gcloud-mcp-oauth-setup/SKILL.md
GitHubGoogle Cloud project + remote MCP with OAuth
Turns a vendor guide for a remote Google MCP server into a working Claude Code entry. The project and APIs are created with gcloud. The consent screen and OAuth client have no gcloud path for this case, so they are done in the Cloud console, driven by browser automation while the user signs in.
The code is the truth: confirm every command, flag and UI label against the live tool or page before stating it as fact. The console labels in references/console-oauth.md were observed in pt-BR and may drift.
Inputs to fix first
| Variable | Meaning | Example |
|---|---|---|
SERVICE_API and MCP_API |
APIs the vendor guide lists | drive.googleapis.com, drivemcp.googleapis.com |
MCP_URL |
Remote endpoint, Streamable HTTP | https://drivemcp.googleapis.com/mcp/v1 |
SCOPES |
OAuth scopes from the vendor guide | .../auth/drive.readonly .../auth/drive.file |
CALLBACK_PORT |
Free local port, same value in Google and in Claude Code | 8765 |
SERVER_NAME |
Letters, digits, hyphen, underscore only | aipp-drive |
Steps
Read the docs. Fetch the vendor guide and the Claude Code MCP docs, with quotes. Treat anything the pages do not state as unknown. Note whether the service is Preview and needs a program sign-up.
Inspect the environment, read-only. Run
gcloud auth list,gcloud config list,claude mcp list. Test each account withgcloud projects list --account=<account>, because the active account can have an expired token while another works. Check whether the project.mcp.jsonis a symlink.Ask the user (interactive question tool, with the reason for each question):
- Which Google account owns the project. It decides which data the MCP reads and whether the consent screen is Internal or External.
- Where to register the server: user scope, or the versioned
.mcp.json.
Create the project and enable the APIs. Pass
--accounton every command so the active gcloud account never changes.PROJECT_ID="<prefix>-$(date +%y%m%d)-$(openssl rand -hex 2)" gcloud projects create "$PROJECT_ID" --name="<Name>" --account=<account> --quiet gcloud services enable $SERVICE_API $MCP_API --project="$PROJECT_ID" --account=<account> gcloud services list --enabled --project="$PROJECT_ID" --account=<account> \ --filter='config.name:(<api1> OR <api2>)' --format='value(config.name)'Proof: the final list shows both APIs. "Operation finished" alone is not proof.
Pick the callback port. Check
ss -ltnfor a free port. The Google redirecthttp://localhost:<CALLBACK_PORT>/callbackand the Claude CodecallbackPortmust match.Configure consent screen, scopes, test user and client in the console. Open the console URL in the browser tool and let the user sign in. The agent never handles the password or 2FA. Follow references/console-oauth.md, including the "AI-powered agent" checkbox and the save pitfalls.
Register the server through the CLI. The client secret enters only through the CLI and is never written to
.mcp.json.cfg=$(jq -cn --arg id "$CLIENT_ID" '{type:"http",url:"<MCP_URL>",oauth:{clientId:$id,callbackPort:<PORT>,scopes:"<SCOPES, space separated>"}}') MCP_CLIENT_SECRET=$(jq -r .web.client_secret <downloaded.json>) \ claude mcp add-json --scope project --client-secret <SERVER_NAME> "$cfg"- Names with
:are rejected. Use a hyphen. - The CLI refuses to write through a symlinked
.mcp.json(SymlinkWriteRefusedError). Run it from the directory that holds the real file. - The CLI reformats the whole file. Restore short arrays and the final newline so the diff shows only the new entry.
- Keep
clientIdliteral. Environment expansion insideoauthfields is not documented.
- Names with
Verify the registration without printing secrets.
claude mcp get <SERVER_NAME> # expect: client_id configured, client_secret configured rg -c 'GOCSPX' <mcp json file> || echo none git diff --statClean up secret-bearing artifacts. The downloaded JSON and the browser tool's snapshots hold the secret.
- Delete the browser output folder and screenshots.
- If
rmis aliased totrash, the files stay in the trash. Check it and delete them for real with/bin/rm. If a safety hook blocks that, hand the exact command to the user. - Stop background processes and confirm the callback port is free. Do not use
pkill -fwith a pattern that matches the shell itself. Write[c]laudeinstead ofclaude.
User approves and authenticates. A server from
.mcp.jsonstays "Pending approval" until the user opensclaudein that directory and approves it. Then run/mcp, select the server and sign in with an account listed as a test user. An unverified-app warning is expected in test mode. Google says the settings can take from 5 minutes to a few hours to apply.Validate with a real tool call, such as searching for a known file. A "Connected" status in
claude mcp listis a hint, not proof.
Known risks
- Developer Preview services can require a program sign-up. Enabling the API does not prove the account was accepted.
- Google needs
access_type=offlineto issue a refresh token. The Claude Code docs do not show how to send it. If sign-in repeats about every hour, this is the likely cause. - The vendor warns about indirect prompt injection, because the server can read and change account data. Review actions before approving them.
Client ID versus client secret
- The client ID is a public identifier (RFC 6749 section 2.2). It appears in every authorization URL and may be committed. Alone it cannot obtain tokens for a web client, because the token exchange needs the secret.
- The client secret must never be committed, printed or placed in a command argument. Supply it through the environment, at registration time only.
- A committed entry only works for whoever holds the secret. Other people or machines get an entry that cannot authenticate. Use user scope when the entry is personal.
Output
Report, in this order: what is proven (command output), what changed (files, with the diff size), what the user still has to do, and risks still open. Do not claim the MCP works until step 11 passes.