Google Workspace MCP

--- **See it in action:** --- ### A quick plug for AI-Enhanced Docs

◆ But why?

**This README was written with AI assistance, and here's why that matters** > > As a solo dev building open source tools, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation. > > In this case, Sonnet 4 took a pass & a human (me) verified them 2/16/26.

## Overview A production-ready MCP server that integrates all major Google Workspace services with AI assistants. It supports both single-user operation and multi-user authentication via OAuth 2.1, making it a powerful backend for custom applications. Built with FastMCP for optimal performance, featuring advanced authentication handling, service caching, and streamlined development patterns. **Simplified Setup**: Now uses Google Desktop OAuth clients - no redirect URIs or port configuration needed! ## Features

**@ Gmail** • **≡ Drive** • **⧖ Calendar** **≡ Docs** - Complete Gmail management, end-to-end coverage - Full calendar management with advanced features - File operations with Office format support - Document creation, editing & comments - Deep, exhaustive support for fine-grained editing --- **≡ Forms** • **@ Chat** • **≡ Sheets** • **≡ Slides** - Form creation, publish settings & response management - Space management & messaging capabilities - Spreadsheet operations with flexible cell management - Presentation creation, updates & content manipulation --- **◆ Apps Script** - Automate cross-application workflows with custom code - Execute existing business logic and custom functions - Manage script projects, deployments & versions - Debug and modify Apps Script code programmatically - Bridge Google Workspace services through automation

**⊠ Authentication & Security** - Advanced OAuth 2.0 & OAuth 2.1 support - Automatic token refresh & session management - Transport-aware callback handling - Multi-user bearer token authentication - Innovative CORS proxy architecture --- **✓ Tasks** • **👤 Contacts** • **◆ Custom Search** - Task & task list management with hierarchy - Contact management via People API with groups - Programmable Search Engine (PSE) integration

--- ## Quick Start

Quick Reference Card - Essential commands & configs at a glance

**Credentials** ```bash export GOOGLE_OAUTH_CLIENT_ID="..." export GOOGLE_OAUTH_CLIENT_SECRET="..." ``` [Full setup →](#credential-configuration)

**Launch Commands** ```bash uvx workspace-mcp --tool-tier core uv run main.py --tools gmail drive ``` [More options →](#start-the-server)

**Tool Tiers** - `core` - Essential tools - `extended` - Core + extras - `complete` - Everything [Details →](#tool-tiers)

#### Required Configuration

Environment Variables _{^{← Click to configure in Claude Desktop}}

**Required** | Variable | Purpose | |----------|---------| | `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud | | `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret | | `OAUTHLIB_INSECURE_TRANSPORT=1` | Development only (allows `http://` redirect) |

**Optional** | Variable | Purpose | |----------|---------| | `USER_GOOGLE_EMAIL` | Default email for single-user auth | | `GOOGLE_PSE_API_KEY` | API key for Custom Search | | `GOOGLE_PSE_ENGINE_ID` | Search Engine ID for Custom Search | | `MCP_ENABLE_OAUTH21` | Set to `true` for OAuth 2.1 support | | `EXTERNAL_OAUTH21_PROVIDER` | Set to `true` for external OAuth flow with bearer tokens (requires OAuth 2.1) | | `WORKSPACE_MCP_STATELESS_MODE` | Set to `true` for stateless operation (requires OAuth 2.1) |

Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.

--- ### One-Click Claude Desktop Install (Claude Desktop Only, Stdio, Single User) 1. **Download:** Grab the latest `google_workspace_mcp.dxt` from the “Releases” page 2. **Install:** Double-click the file – Claude Desktop opens and prompts you to **Install** 3. **Configure:** In Claude Desktop → **Settings → Extensions → Google Workspace MCP**, paste your Google OAuth credentials 4. **Use it:** Start a new Claude chat and call any Google Workspace tool > **Why DXT?** > Desktop Extensions (`.dxt`) bundle the server, dependencies, and manifest so users go from download → working MCP in **one click** – no terminal, no JSON editing, no version conflicts. --- ### Prerequisites - **Python 3.10+** - **[uvx](https://github.com/astral-sh/uv)** (for instant installation) or [uv](https://github.com/astral-sh/uv) (for development) - **Google Cloud Project** with OAuth 2.0 credentials ### Configuration

Google Cloud Setup _{^{← OAuth 2.0 credentials & API enablement}}

**1. Create Project** ```text console.cloud.google.com → Create new project → Note project name ``` [Open Console →](https://console.cloud.google.com/)	**2. OAuth Credentials** ```text APIs & Services → Credentials → Create Credentials → OAuth Client ID → Desktop Application ``` Download & save credentials	**3. Enable APIs** ```text APIs & Services → Library Search & enable: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, People, Chat, Search ``` See quick links below
OAuth Credential Setup Guide ← Step-by-step instructions **Complete Setup Process:** 1. **Create OAuth 2.0 Credentials** - Visit [Google Cloud Console](https://console.cloud.google.com/) - Create a new project (or use existing) - Navigate to **APIs & Services → Credentials** - Click **Create Credentials → OAuth Client ID** - Choose **Desktop Application** as the application type (no redirect URIs needed!) - Download credentials and note the Client ID and Client Secret 2. **Enable Required APIs** - In **APIs & Services → Library** - Search for and enable each required API - Or use the quick links below for one-click enabling 3. **Configure Environment** - Set your credentials: ```bash export GOOGLE_OAUTH_CLIENT_ID="your-client-id" export GOOGLE_OAUTH_CLIENT_SECRET="your-secret" ``` [Full Documentation →](https://developers.google.com/workspace/guides/auth-overview)

Quick API Enable Links ---