Quick Start Guide

Get your Google Workspace MCP Server up and running in minutes. Follow these simple steps to connect your AI assistant to Google Workspace.

⏱️
~5-10 min Setup Time
🛠️
10 Simple Steps
🚀
9 Google Services
1

✨ 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.

Features:
  • 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

Download
⚙️

Alternative: Traditional Installation

Skip to step 2 for manual setup

2

📋 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) Required
☁️
Google Cloud Project with OAuth 2.0 credentials Required
3

⚡ 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.

Terminal 
# 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

Terminal 
# 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
4

⚙️ Configuration

Set up OAuth 2.0 credentials and API access

1

Google Cloud Setup Google Cloud Console

Create OAuth 2.0 credentials (web application) in Google Cloud Console

2

Enable Required APIs

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

3

Configure Redirect URI

Add redirect URI to your OAuth client configuration

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.

4

Configure Credentials

Configure credentials using one of these methods:

5

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
6

Option B: File-based (Traditional)

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.

7

Credential Loading Priority

1. Environment variables (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET) 2. File specified by GOOGLE_CLIENT_SECRET_PATH or GOOGLE_CLIENT_SECRETS environment variable 3. Default file (client_secret.json in project root)

8

Why Environment Variables?

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

9

Security Warning

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

5

🔧 Server Configuration

Customize server settings with environment variables

Terminal 
export WORKSPACE_MCP_BASE_URI="https://my-custom-domain.com"
export WORKSPACE_MCP_PORT="9000"
uv run main.py
WORKSPACE_MCP_BASE_URI Default: 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 Default: 8000

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

6

🌍 Environment Setup

Configure OAuth for development

Terminal 
# 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.

7

🚀 Start the Server

Choose your preferred method to run the server

💡

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.

uvx (Recommended)

Default stdio mode for MCP clients like Claude Desktop

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

# HTTP mode (for web interfaces and debugging)
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

Terminal 
# 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

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

🔗 Connecting to Claude Desktop

Connect your AI assistant to the MCP server

Auto-install (Recommended)

Use the auto-installer script

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

Manual Configuration (uvx)

Manual setup for stdio mode (recommended)

claude_desktop_config.json:

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

Development Installation

For development setups

claude_desktop_config.json:

Configuration 
{
  "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:

Configuration 
{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

Integration with Open WebUI

Use the server as a tool provider within Open WebUI

Step 1: Create MCPO Configuration
  1. Create a config.json file with the server configuration
  2. Configure the streamable HTTP endpoint for OpenAPI access
Step 2: Start MCPO Server
  1. Install mcpo: pip install mcpo
  2. Start mcpo: mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
  3. The proxy serves your Google Workspace MCP on port 8001
Step 3: Configure Open WebUI
  1. Navigate to Open WebUI settings → Connections → Tools
  2. Click "Add Tool"
  3. Enter Server URL: http://localhost:8001/google_workspace
  4. Enter API Key if you used one with mcpo
  5. Save the configuration
9

🔐 First-time Authentication

Complete the OAuth flow for Google services

When a tool requiring Google API access is called:

If user_google_email is provided to the tool and credentials are missing/invalid:

The server automatically initiates the OAuth 2.0 flow. An authorization URL will be returned in the MCP response (or printed to the console).

If user_google_email is NOT provided and credentials are missing/invalid:

The tool will return an error message guiding the LLM to use the centralized start_google_auth tool. The LLM should then call start_google_auth with the user's email and the appropriate service_name (e.g., "Google Calendar", "Google Docs", "Gmail", "Google Drive"). This will also return an authorization URL.

Steps for the User (once an authorization URL is obtained):

  1. Open the provided authorization URL in a web browser
  2. Log in to the Google account and grant the requested permissions for the specified service
  3. After authorization, Google will redirect the browser to http://localhost:8000/oauth2callback (or your configured redirect URI)
  4. The MCP server handles this callback, exchanges the authorization code for tokens, and securely stores the credentials
  5. The LLM can then retry the original request. Subsequent calls for the same user and service should work without re-authentication until the refresh token expires or is revoked
10

🔍 Google Custom Search Setup (Optional)

Configure Google Custom Search for web search capabilities

💡

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

1

Create a Programmable Search Engine Create Search Engine

Go to Programmable Search Engine Control Panel and configure sites to search (or search the entire web). Note your Search Engine ID (cx parameter).

2

Get an API Key Custom Search API Documentation

Visit Google Developers Console, create or select a project, enable the Custom Search API, and create credentials (API Key).

3

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"
4

Enable Custom Search API Enable Custom Search API

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

🎉

You're All Set!

Your Google Workspace MCP Server is now ready to use. Start building amazing AI integrations with Google Workspace!

View API Documentation View on GitHub