title: Google Workspace MCP Server emoji: 📧 colorFrom: blue colorTo: green sdk: docker app_file: app.py pinned: false

Google Workspace Model Context Protocol (MCP) Server

A reusable, production-ready Model Context Protocol (MCP) Server that bridges AI agents with Google Workspace services (Gmail & Google Docs). By exposing standardized productivity tools, this server allows any MCP-compatible AI agent (such as Claude Desktop, IDE assistants, or autonomous workflows) to securely compose emails and edit documents without requiring hardcoded Google API logic.

Related MCP server: google-cli-mcp

Features & Capabilities

📧 Gmail Integration

• send_email: Send emails immediately with validation for to, cc, and bcc lists. Supports both plain text and HTML alternative body rendering.

• draft_email: Create drafts in your Gmail mailbox for subsequent manual review before sending.

📄 Google Docs Integration

• append_content: Append plain text or formatted notes to the end of any Google Document. Supports Heading styles (HEADING_1, HEADING_2, HEADING_3), bulleted lists, numbered lists, bold text, and italic text.

🔐 Secure & Transparent Authentication

• Implements Google OAuth 2.0 with PKCE for enhanced desktop security.

• Automatically checks token expiration and performs silent background refreshes using stored refresh tokens without interrupting AI agent execution.

• AI agents are strictly isolated from raw tokens or client secrets.

Quickstart Guide

1. Requirements & Setup

Ensure you have Python 3.10+ installed. Create a virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

2. Configure OAuth Client Secrets

1. Follow the step-by-step instructions in docs/GCP_SETUP.md to enable Gmail and Docs APIs in Google Cloud Console.

2. Download your Desktop App OAuth client secrets JSON file.

3. Save the downloaded file to your project root or configure its path in your .env file:

   GOOGLE_CLIENT_SECRETS_FILE=client_secret_YOUR_ID.json
   TOKEN_STORAGE_PATH=token.json
   LOG_LEVEL=INFO

3. Authorize Your Google Account

Before running the MCP server, perform a one-time interactive login to generate your token.json:

workspace-auth

(This opens a browser window. Sign in with your Google account and grant permissions).

Connecting to AI Agents

Option A: Claude Desktop Configuration

To connect this MCP server to Claude Desktop, add the following entry to your claude_desktop_config.json (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google-workspace": {
      "command": "/Users/vkg/Desktop/MCP Server/.venv/bin/workspace-mcp",
      "args": ["--transport", "stdio"],
      "cwd": "/Users/vkg/Desktop/MCP Server",
      "env": {
        "GOOGLE_CLIENT_SECRETS_FILE": "/Users/vkg/Desktop/MCP Server/client_secret_YOUR_ID.json",
        "TOKEN_STORAGE_PATH": "/Users/vkg/Desktop/MCP Server/token.json"
      }
    }
  }
}

Option B: Run via Server-Sent Events (SSE)

For network-based AI agents, launch the server in SSE mode:

workspace-mcp --transport sse --port 8000

Then connect your client to http://localhost:8000/sse.

Documentation Suite

• Hugging Face Deployment Guide: Complete step-by-step tutorial for cloud container hosting on Hugging Face Spaces.

• GCP Setup Guide: Detailed step-by-step tutorial on creating GCP projects and credentials.

• Configuration Guide: Advanced environment variables, scopes, and multi-account readiness.

• Troubleshooting Guide: Solutions for common OAuth errors, token expiration, and permission denials.

• Problem Statement & Architecture: Architectural specifications and tool schemas.