gwmcp

Google Workspace MCP Server with guided setup and seamless auth.

One command to install, authenticate, and start using 114 Google Workspace tools with Claude Code, Cursor, or any MCP client.

Derived from taylorwilsdon/google_workspace_mcp (MIT). This project adds a guided setup wizard, simplified configuration, and improved auth flow for local single-user setups.

Table of Contents

• Quick Start

• Step-by-Step Google Cloud Setup

• What You Get

• Configuration

• CLI Options

• How It Improves on the Original

• Development

• License

Related MCP server: google-workspace-mcp-with-script

Quick Start

If you already have a client_secret.json from Google Cloud, you can skip ahead:

uvx gwmcp setup --email you@gmail.com --client-secret /path/to/client_secret.json

If you don't have one yet, follow the step-by-step guide below.

Step-by-Step Google Cloud Setup

This section walks you through everything from scratch. No prior Google Cloud experience needed.

1. Install Prerequisites

You need Python 3.10+ and uv (a fast Python package manager).

Windows (PowerShell):

# Install uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

After installing, restart your terminal so the uvx command is available.

2. Create a Google Cloud Project

1. Go to Google Cloud Console

2. Sign in with your Google account

3. Click the project dropdown at the top of the page (it might say "Select a project")

4. Click New Project

5. Give it a name (e.g. "My Workspace MCP") and click Create

6. Make sure your new project is selected in the dropdown

3. Enable Google APIs

You need to turn on the APIs for the Google services you want to use.

1. In the Google Cloud Console, go to APIs & Services > Library (or click here)

2. Search for and enable each API you need by clicking on it and hitting Enable:

You can enable just the ones you need now and add more later.

4. Set Up the OAuth Consent Screen

This tells Google what your app is and who can use it.

1. Go to APIs & Services > OAuth consent screen (or click here)

2. Select Get started or External as the user type, then click Create

3. Fill in the required fields:

   • App name: anything (e.g. "gwmcp")

   • User support email: your email

   • Developer contact email: your email

4. Click Save and Continue through the Scopes and Summary steps (defaults are fine)

5. On the Test users page or under Audience, click Add Users

6. Add your own Gmail address (e.g. you@gmail.com) and click Save

Important: While the app is in "Testing" mode, only the email addresses you add as test users can authenticate. This is fine for personal use.

5. Create OAuth Credentials

This generates the client_secret.json file you need.

1. Go to APIs & Services > Credentials (or click here)

2. Click Create Credentials at the top

3. Choose OAuth client ID

4. For Application type, select Desktop app

5. Give it a name (e.g. "gwmcp") and click Create

6. A dialog will appear with your client ID and secret — click Download JSON

7. Save the downloaded file somewhere you can find it (e.g. your Downloads folder)

The file will have a long name like client_secret_284692452895-xxxxx.apps.googleusercontent.com.json. That's normal.

6. Run the Setup Wizard

Now you have everything you need. Run this in your terminal:

uvx gwmcp setup --email you@gmail.com --client-secret ~/Downloads/client_secret_*.json

Replace you@gmail.com with your actual Gmail address, and update the path to wherever you saved the JSON file.

The wizard will:

1. Copy your credentials to a safe location (~/.google_workspace_mcp/)

2. Open your browser for Google sign-in

3. Save the authentication token

4. Write the MCP config file for Claude Code

When the browser opens:

• Sign in with the same Google account you added as a test user

• You'll see a warning: "Google hasn't verified this app" — click Advanced, then Go to gwmcp (unsafe)

• Check the permissions and click Allow

• You'll see a success page — you can close the browser tab

7. Restart Claude Code

Close and reopen Claude Code. The Google Workspace tools will now be available. Try asking:

"Search my Google Drive for recent documents"

Or if you prefer the interactive setup (prompts you for each step):

uvx gwmcp setup

What You Get

114 tools across 12 Google Workspace services:

Configuration

After gwmcp setup, your ~/.claude/mcp.json will look like:

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["gwmcp", "--single-user"],
      "env": {
        "GOOGLE_CLIENT_SECRET_PATH": "/path/to/.google_workspace_mcp/client_secret.json"
      }
    }
  }
}

Only one environment variable needed. The email and OAuth credentials are auto-detected from stored tokens.

Environment Variables

CLI Options

gwmcp --single-user                    # Single-user mode (recommended)
gwmcp --tools gmail drive docs         # Load specific services only
gwmcp --tool-tier core                 # Load core tools only
gwmcp --read-only                      # Read-only mode
gwmcp --permissions gmail:readonly drive:full  # Granular permissions
gwmcp --cli search_drive_files --args '{"query": "test"}'  # Direct CLI usage

How It Improves on the Original

Troubleshooting

"Google hasn't verified this app"

This appears because your app is in "Testing" mode. To get past it:

1. Click Advanced, then Go to gwmcp (unsafe) to continue

2. If you get blocked entirely, make sure your email is added as a test user:

   • Go to Google Cloud Console > APIs & Services > OAuth consent screen

   • Under Audience (or Test users), click Add Users

   • Add the Gmail address you're trying to sign in with

   • Save and try again

"Access blocked: This app's request is invalid"

Make sure the redirect URI matches. gwmcp uses http://localhost:8000/oauth2callback. You don't need to configure this in Google Cloud for Desktop app credentials — it's handled automatically.

"uvx: command not found"

You need to install uv first. See Install Prerequisites.

Port 8000 is in use

Another application is using port 8000. Stop it and try again, or set a custom port:

WORKSPACE_MCP_PORT=9000 uvx gwmcp setup --email you@gmail.com --client-secret /path/to/secret.json

Token expired or revoked

Re-run the setup wizard to re-authenticate:

uvx gwmcp setup

Development

git clone https://github.com/Gambinoo3005/gwmcp.git
cd gwmcp
pip install -e ".[dev]"
pytest

License

MIT License. See LICENSE.

Based on google_workspace_mcp by Taylor Wilsdon.