gcloud-workspace-mcp

An MCP server for Google Docs, Drive and Gmail that authenticates through your local gcloud CLI. It doesn't need an OAuth client of its own.

Why it exists

Some Google Workspace tenants block every third-party OAuth client. Other Workspace MCP servers ask you to register or reuse an OAuth client ID, and on those tenants the sign-in stops at an "access blocked by your admin" screen. Google's own Cloud SDK client usually stays allowed. So this server borrows the access tokens that gcloud mints on your machine and calls the Google REST APIs over HTTPS.

If your tenant lets you register an OAuth app, a full-featured server such as google_workspace_mcp will cover more of the API. Use this one when gcloud is the only client you can log in with.

The only dependency is the mcp SDK. The HTTP layer uses the Python standard library.

Related MCP server: Google Docs & Gmail MCP Server

Two credential stores

gcloud keeps two token stores, and you can't swap one for the other. A 403 usually means a call used the wrong one.

One-time setup

Install the Google Cloud SDK so gcloud is on your PATH. Then grant the scopes. The server never runs these commands for you.

Docs and Drive (user credentials):

# Grants the full drive scope. gcloud has no read-only variant.
gcloud auth login --enable-gdrive-access

Gmail (Application Default Credentials):

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/gmail.readonly
gcloud auth application-default set-quota-project <your-quota-project>

Keep cloud-platform in the list if other tools on your machine use ADC for Google Cloud. The login rewrites ~/.config/gcloud/application_default_credentials.json in place, so back it up first if you care about its current scopes.

Install and register

You need uv. Register the server in Claude Code:

claude mcp add -s user gcloud-workspace \
  -e GCLOUD_QUOTA_PROJECT=<your-quota-project> \
  -- uvx --from git+https://github.com/thrix/gcloud-workspace-mcp gcloud-workspace-mcp

For another client, add this to its MCP config:

{
  "mcpServers": {
    "gcloud-workspace": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/thrix/gcloud-workspace-mcp",
        "gcloud-workspace-mcp"
      ],
      "env": { "GCLOUD_QUOTA_PROJECT": "<your-quota-project>" }
    }
  }
}

Pin a release by appending @v0.1.0 to the git URL.

Container

CI publishes a multi-arch image (amd64, arm64) to ghcr.io/thrix/gcloud-workspace-mcp. It holds the server and the Google Cloud SDK on a distroless Hummingbird Python image. You still do the one-time gcloud logins on your host. The container reads and refreshes the tokens through a mount of your gcloud config directory.

mkdir -p -m 700 "$HOME/.cache/gcloud-workspace-mcp/downloads"
claude mcp add -s user gcloud-workspace -- \
  podman run -i --rm --userns=keep-id:uid=65532,gid=65532 \
    -v "$HOME/.config/gcloud:/gcloud:z" \
    -v "$HOME/.cache/gcloud-workspace-mcp/downloads:$HOME/.cache/gcloud-workspace-mcp/downloads:z" \
    -e GCLOUD_WORKSPACE_DOWNLOAD_DIR="$HOME/.cache/gcloud-workspace-mcp/downloads" \
    -e GCLOUD_QUOTA_PROJECT=<your-quota-project> \
    ghcr.io/thrix/gcloud-workspace-mcp:latest

--userns=keep-id maps your host user to the image's UID 65532, so gcloud can write refreshed tokens back to your config. The downloads directory is mounted at the same path it has on your host, so the paths the server returns work outside the container too. Pass -e GCLOUD_WORKSPACE_ENABLE_WRITES=1 to enable the write tools.

Each published image carries a signed build provenance attestation. Check it with gh attestation verify oci://ghcr.io/thrix/gcloud-workspace-mcp:latest --owner thrix.

To build the image yourself, run podman build -t gcloud-workspace-mcp . and use gcloud-workspace-mcp as the image name. To pick a different SDK release, pass --build-arg GCLOUD_VERSION=<version> together with that release's GCLOUD_SHA256_X86_64 and GCLOUD_SHA256_ARM. The build checks the tarball against them.

Environment

Tools

Drive and Docs use the user credentials:

Text comes back 50,000 characters at a time. When there is more, the result ends with a note that gives the offset for the next call.

PDF exports and binary downloads don't go into the tool result, since base64 would blow past the client's output limit. The server saves them to the download directory as <file id>.<ext> and returns {path, name, mimeType, bytes}. Claude Code can open the PDF or image at that path with its Read tool. The directory is created with mode 0700 and each file with 0600. A second download of the same file overwrites the first.

Gmail uses ADC plus the quota header:

Writes

The write tools stay unregistered until you set GCLOUD_WORKSPACE_ENABLE_WRITES=1, so your MCP client can't see or call them by default.

The server offers no tool that sends mail, deletes files or moves them to the trash.

Drafts need one more ADC scope:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.compose

Prompt injection. The model reads your documents and mail, and anyone who can share a doc or send you an email can put instructions in it. With writes on, a poisoned doc could get the model to overwrite another doc or draft a message to someone. Turn writes on when you need them and review what the model changes.

Security

• The server gets tokens only by reading the stdout of the gcloud subprocess. It never puts a token on a command line.

• It never logs a token or returns one in a tool result or error message.

• It attaches a token only to https URLs on a *.googleapis.com host. It checks this before it mints the token, checks every redirect target the same way, and refuses every other URL.

See SECURITY.md to report a vulnerability.

Limitations

• You need a logged-in gcloud on the same machine. The server can't run an interactive login. When gcloud asks for reauthentication, the tool error tells you, and you re-run the login. The server gives gcloud no stdin, so a prompt fails instead of waiting, and it stops a gcloud call after 60 seconds.

• print-access-token doesn't report an expiry. The server assumes a 55-minute lifetime, refreshes 5 minutes early, and retries once after a 401.

• Gmail calls need GCLOUD_QUOTA_PROJECT, and they fail with 403 accessNotConfigured until that project enables the Gmail API. Drive and Docs calls don't send that header. They bill the Cloud SDK's own project, and GCLOUD_QUOTA_PROJECT can't enable an API for them.

• Message bodies get cut at 50,000 characters, and a thread's bodies at 100,000 in total. Attachments come back as names and sizes only. HTML-only mail keeps table cells apart and shows each link target after its text.

License

MIT