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

---

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:

API	What it unlocks
Google Drive API	Search, upload, download, share files
Google Docs API	Create, read, edit documents
Google Sheets API	Read, write, format spreadsheets
Gmail API	Search, read, send, draft emails
Google Calendar API	Events, availability, calendars
Google Slides API	Create, edit presentations
Google Forms API	Create forms, read responses
Tasks API	Manage task lists and tasks
People API	Manage contacts
Google Chat API	Spaces and messages
Apps Script API	Manage script projects

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:

Service	Examples
Gmail	Search, read, send, draft, label, filter
Drive	Search, upload, download, share, permissions
Docs	Create, read, edit, find & replace, export to PDF
Sheets	Read, write, format, conditional formatting
Calendar	Events, availability, multiple calendars
Slides	Create, read, edit presentations
Forms	Create, read responses
Tasks	Create, manage task lists
Contacts	Search, create, manage
Chat	Spaces, messages
Apps Script	Projects, deployments, versions
Search	Custom search engine

---

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

Variable	Required	Description
GOOGLE_CLIENT_SECRET_PATH	Yes	Path to your client_secret.json
USER_GOOGLE_EMAIL	No	Auto-detected from stored credentials
GOOGLE_OAUTH_CLIENT_ID	No	Auto-extracted from client_secret.json
GOOGLE_OAUTH_CLIENT_SECRET	No	Auto-extracted from client_secret.json

---

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

Pain point	Original	gwmcp
Env vars needed	4 (trial and error)	1 (GOOGLE_CLIENT_SECRET_PATH)
Email config	Manual USER_GOOGLE_EMAIL required	Auto-detected from stored credentials
First-time auth	Print URL, no callback server, state mismatch	Setup wizard handles everything
CLI mode auth	Prints dead URL, exits	Opens browser, waits, retries automatically
Setup process	Read docs, edit JSON manually	uvx gwmcp setup
Tool responses	Verbose JSON with raw IDs	Clean, human-readable output

---

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.