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.

⏱️
~10 min Setup Time
🛠️
8 Simple Steps
🚀
5+ Google Services
1

📋 Prerequisites

Ensure you have the required tools and accounts

🐍
Python 3.11+ Required
📦
uv package installer (or pip) Required
☁️
Google Cloud Project with OAuth 2.0 credentials Required
2

⚡ Installation

Clone the repository and install dependencies

Terminal 
# Clone the repository (replace with your fork URL if different)
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
uv pip install -e .
3

⚙️ Configuration

Set up OAuth 2.0 credentials and API access

1

Create OAuth 2.0 Credentials Google Cloud Console

Set up web application credentials in Google Cloud Console

2

Enable Required APIs

Enable Google Calendar API, Google Drive API, Gmail API, and Google Docs API for your project

3

Download Credentials

Download the OAuth client credentials as client_secret.json and place it in the project's root directory

4

Configure Redirect URI

Add the following redirect URI to your OAuth client configuration

http://localhost:8000/oauth2callback

Note that http://localhost:8000 is the default base URI and port, which can be customized via environment variables (WORKSPACE_MCP_BASE_URI and WORKSPACE_MCP_PORT). If you change these, you must update the redirect URI in the Google Cloud Console accordingly.

5

Security Warning

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

4

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

5

🌍 Environment Setup

Configure OAuth for development

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

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

6

🚀 Start the Server

Choose your preferred method to run the server

HTTP Server Mode

Runs the server with an HTTP transport layer on port 8000

Terminal 
python main.py
# or using uv
uv run main.py

Single-User Mode

Simplified single-user environment that bypasses session-to-OAuth mapping

Terminal 
python main.py --single-user
# or using uv
uv run main.py --single-user
Features:
  • The server automatically finds and uses any valid credentials in the .credentials directory
  • No session mapping is required - the server uses the first valid credential file found
  • Useful for development, testing, or single-user deployments
  • Still requires initial OAuth authentication to create credential files
💡

This mode is particularly helpful when you don't need multi-user session management and want simplified credential handling.

Using Docker

Build and run the server using the provided Dockerfile

Terminal 
# Build the Docker image
docker build -t google-workspace-mcp .

# Run the Docker container
# The -p flag maps the container port 8000 to the host port 8000
# The -v flag mounts the current directory to /app inside the container
# This is useful for development to pick up code changes without rebuilding
docker run -p 8000:8000 -v $(pwd):/app google-workspace-mcp
💡

The smithery.yaml file is configured to start the server correctly within the Docker container.

7

🔗 Connecting to the Server

Connect your AI assistant to the MCP server

Claude Desktop

Can run anywhere and be used via mcp-remote or invoked locally

config.json:

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

Using mcpo (Recommended for OpenAPI Spec Access)

Provides OpenAPI documentation and Swagger UI

With config.json (for multi-mcp mcpo usage)
  1. Install mcpo: uv pip install mcpo or pip install mcpo
  2. Create a config.json (see Integration with Open WebUI)
  3. Run mcpo pointing to your config: uvx mcpo --config config.json --port 8001
  4. The MCP server API will be available at: http://localhost:8001/google_workspace
  5. OpenAPI documentation (Swagger UI) available at: http://localhost:8001/google_workspace/docs
With startup command (for single-mcp mcpo usage)
  1. Install mcpo: uv pip install mcpo or pip install mcpo
  2. Start with uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp
  3. The MCP server API will be available at: http://localhost:8001/openapi.json
  4. OpenAPI documentation (Swagger UI) available at: http://localhost:8001/docs

HTTP Mode

Direct HTTP communication for testing and custom clients

  1. Start the server in HTTP mode (see Start the Server)
  2. Send MCP JSON requests directly to http://localhost:8000
  3. Useful for testing with tools like curl or custom HTTP clients
  4. Can be used to serve Claude Desktop & other MCP clients yet to integrate the new Streamable HTTP transport via mcp-remote
  5. You can also serve in SSE fallback mode if preferred
8

🔐 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
🎉

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