managing-google-workspace

Google Workspace -- Tool Router

Execution Mode

Detect which mode is available and use it.

MCP (preferred)

If MCP tools from the google-workspace server are available, call them directly. The tool names in the tables below are the base names -- prefix with the server name as needed (e.g. google-workspace:search_gmail_messages).

CLI (no MCP)

If no MCP tools are available, execute via bash:

uvx workspace-mcp --cli <tool_name> --args '{"user_google_email": "USER_EMAIL", ...}'

Before calling a tool, read the relevant reference file for exact parameter names and types. Only use parameters documented there -- do not invent parameters.

First-Time Setup

If a tool call fails with a credential error, walk the user through this setup.

1. Create OAuth credentials

Direct the user to Google Cloud Console:

• Create OAuth 2.0 Client ID (Desktop application type)
• Enable the Google APIs they need (Gmail, Drive, Calendar, etc.)
• Copy the Client ID and Client Secret

2. Store credentials

Direct the user to edit ~/.claude/settings.local.json themselves (this file is gitignored and never shared). Do not ask the user to paste secrets into the conversation. Tell them to add the following to the env block:

{
  "env": {
    "GOOGLE_OAUTH_CLIENT_ID": "their-client-id",
    "GOOGLE_OAUTH_CLIENT_SECRET": "their-secret"
  }
}

If settings.local.json already exists, they should merge into the existing env object, not replace it. These env vars are inherited by all MCP servers and CLI processes that Claude Code spawns.

3. Authenticate

• MCP mode: call start_google_auth to open the browser OAuth flow
• CLI mode: run any tool -- the first invocation opens the OAuth flow
• Credentials are cached in ~/.google_workspace_mcp/credentials (or as configured by WORKSPACE_MCP_CREDENTIALS_DIR) for future sessions

For server options, transport, auth modes, tool filtering, and deployment: references/server-options.md