Quick start

Workspace MCP in 5 concise steps

A streamlined setup for Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, and Chat tools.

One-Click Installation (Recommended)

Get started instantly with our Desktop Extension - no terminal or JSON editing required

Desktop Extension (.dxt)

Download and double-click to install directly into Claude Desktop. This bundles the server, dependencies, and manifest so you go from download → working MCP in one click.

No terminal commands required
No JSON configuration files to edit
Automatic dependency management
Zero version conflicts
One-click installation and updates

After installation, you'll just need to add your Google OAuth credentials in Claude Desktop's extension settings.

📦

Download .dxt File

Get the latest release from GitHub

Prerequisites (Traditional Install)

Ensure you have the required tools and accounts for manual installation

🐍

Python 3.11+

Required
📦

uvx (for instant installation) or uv (for development)
Details
Required
☁️

Google Cloud Project with OAuth 2.0 credentials

Required

Installation Options

Choose your preferred installation method

Simplest Start (uvx - Recommended)

Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the GOOGLE_CLIENT_SECRET_PATH (or legacy GOOGLE_CLIENT_SECRETS) environment variable to point to your client_secret.json file.

# Set OAuth credentials via environment variables (recommended)
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# Start the server with all Google Workspace tools
uvx workspace-mcp

# Start with specific tools only
uvx workspace-mcp --tools gmail drive calendar

# Start in HTTP mode for debugging
uvx workspace-mcp --transport streamable-http

Requires Python 3.11+ and uvx. You must configure OAuth credentials when using uvx.

Development Installation

For development or customization

# Clone the repository
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

# Run directly with uv
uv run main.py

Configuration

Set up OAuth 2.0 credentials and API access

Google Cloud Setup - Simplified!

Create OAuth 2.0 credentials using Desktop Application type (recommended - no redirect URI configuration needed!) or Web Application type in Google Cloud Console

Google Cloud Console

Enable Required APIs

Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Chat

Configure Redirect URI (Web Application Only)

Add redirect URI to your OAuth client configuration - ONLY needed if using Web Application credentials. Desktop Application credentials skip this step!

http://localhost:8000/oauth2callback

Default base URI is http://localhost:8000, customizable via environment variables (WORKSPACE_MCP_BASE_URI and WORKSPACE_MCP_PORT). Update the redirect URI in Google Cloud Console if you change these. With Desktop Application credentials, this step is not required.

Configure Credentials

Configure credentials using one of these methods:

Option A: Environment Variables (Recommended for Production)

Set OAuth credentials via environment variables

export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional

Option B: .env File (Recommended for Development)

Copy the provided `.env.oauth21` example file to `.env` in the project root and add your credentials. The server automatically loads variables from this file on startup.

cp .env.oauth21 .env

Option C: File-based (Legacy)

Download credentials as client_secret.json in project root. To use a different location, set GOOGLE_CLIENT_SECRET_PATH (or legacy GOOGLE_CLIENT_SECRETS) environment variable with the file path.

Credential Loading Priority

The server loads credentials in the following order of precedence: 1. Manually set environment variables (e.g., `export VAR=value`). 2. Variables defined in a `.env` file in the project root. 3. `client_secret.json` file specified by `GOOGLE_CLIENT_SECRET_PATH`. 4. Default `client_secret.json` file in the project root.

Why Environment Variables?

✅ Containerized deployments (Docker, Kubernetes) ✅ Cloud platforms (Heroku, Railway, etc.) ✅ CI/CD pipelines ✅ No secrets in version control ✅ Easy credential rotation

Security Warning

Important

Ensure client_secret.json is added to your .gitignore file and never committed to version control

Server Configuration

Customize server settings with environment variables

Variable Default Description

WORKSPACE_MCP_BASE_URI http://localhost Sets the base URI for the server. This affects the server_url used for Gemini native function calling and the OAUTH_REDIRECT_URI.

WORKSPACE_MCP_PORT 8000 Sets the port the server listens on. This affects the server_url, port, and OAUTH_REDIRECT_URI.

GOOGLE_OAUTH_REDIRECT_URI Auto-generated from base URI and port Override the OAuth redirect URI for reverse proxy configurations (e.g., when running behind Nginx or Cloudflare).

# Standard configuration
export WORKSPACE_MCP_BASE_URI="https://my-custom-domain.com"
export WORKSPACE_MCP_PORT="9000"

# Reverse proxy configuration (Nginx, Cloudflare, etc.)
export GOOGLE_OAUTH_REDIRECT_URI="https://my-domain.com/oauth2callback"

uv run main.py

Reverse Proxy Support

Configure the server when running behind reverse proxies like Nginx or Cloudflare

When to Use Reverse Proxy Configuration

Use this when your server runs behind a reverse proxy (Nginx, Cloudflare, Apache, etc.) that changes the external URL.

Set the Redirect URI Override

Override the auto-generated OAuth redirect URI to match your external URL

export GOOGLE_OAUTH_REDIRECT_URI="https://your-external-domain.com/oauth2callback"

Update Google Cloud Console

Make sure the redirect URI in your Google Cloud OAuth credentials matches the external URL you configured.

This ensures OAuth callbacks work correctly when your server is accessible through a different URL than localhost.

Environment Setup

Configure OAuth for development

# Allow HTTP for localhost OAuth callbacks (development only!)
export OAUTHLIB_INSECURE_TRANSPORT=1

# Optional: Set OAuth credentials via environment variables (recommended)
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# Optional: Default email for single-user setups
export USER_GOOGLE_EMAIL="[email protected]"

# Optional: Google Custom Search configuration
export GOOGLE_PSE_API_KEY="your-custom-search-api-key"
export GOOGLE_PSE_ENGINE_ID="your-search-engine-id"

# Optional: Customize server settings
export WORKSPACE_MCP_BASE_URI="http://localhost"
export WORKSPACE_MCP_PORT="8000"

Without this, you might encounter an "OAuth 2 MUST utilize HTTPS" error during the authentication flow.

Start the Server

Choose your preferred method to run the server

uvx (Recommended)

Default stdio mode for MCP clients like Claude Desktop

# Default (stdio mode for MCP clients)
uvx workspace-mcp

# HTTP mode (for web interfaces and debugging)
uvx workspace-mcp --transport streamable-http

# Enable OAuth 2.1 for multi-user support
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http

# Single-user mode (simplified authentication)
uvx workspace-mcp --single-user

# Selective tool registration
uvx workspace-mcp --tools gmail drive calendar

Development Mode

For development installations

# Default (stdio mode for MCP clients)
uv run main.py

# HTTP mode (for web interfaces and debugging)
uv run main.py --transport streamable-http

# Single-user mode (simplified authentication)
uv run main.py --single-user

# Selective tool registration
uv run main.py --tools gmail drive calendar

Using Docker

Build and run the server using the provided Dockerfile

docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http

Available Tools for --tools flag: gmail, drive, calendar, docs, sheets, slides, forms, tasks, chat, search. Google Custom Search requires additional setup with GOOGLE_PSE_API_KEY and GOOGLE_PSE_ENGINE_ID environment variables.

Connecting to Claude Desktop

Connect your AI assistant to the MCP server

Available tools for --tools: gmail, drive, calendar, docs, sheets, slides, forms, tasks, chat, search. Search requires GOOGLE_PSE_API_KEY and GOOGLE_PSE_ENGINE_ID.

Auto-install (Recommended)

Use the auto-installer script

Download and run the installer: python install_claude.py
The script will automatically configure Claude Desktop for you

Manual Configuration (uvx)

Manual setup for stdio mode (recommended)

claude_desktop_config.json:

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"]
    }
  }
}

Development Installation

For development setups

claude_desktop_config.json:

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/google_workspace_mcp"
    }
  }
}

HTTP Mode (For debugging)

If you need to use HTTP mode with Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": ["run", "main.py", "--transport", "streamable-http"],
      "cwd": "/path/to/google_workspace_mcp"
    }
  }
}

Google Custom Search Setup

Configure Google Custom Search for web search capabilities

Create a Programmable Search Engine

Go to the Programmable Search Engine control panel and create a new search engine.

Programmable Search Engine Console

Get Search Engine ID

Copy the Search engine ID from the control panel.

Get API Key

Click "API Key" in the control panel to get your Custom Search API key.

Configure Environment Variables

Set the required environment variables for Google Custom Search

export GOOGLE_PSE_API_KEY="your-custom-search-api-key"
export GOOGLE_PSE_ENGINE_ID="your-search-engine-id"

Enable Custom Search API

In the Google Cloud Console, go to APIs & Services → Library, search for and enable the Custom Search API.

Enable Custom Search API

Google Custom Search is optional. The server will work without it, but search tools will not be available.