google-workspace-mcp-advanced 1.0.0

Advanced Google Workspace MCP Server - Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Search with bidirectional sync

Google Workspace MCP Advanced

Advanced Model Context Protocol (MCP) server for Google Workspace integration.

This project is an advanced fork of taylorwilsdon/google_workspace_mcp, merged with advanced file synchronization features from the drive-synapsis MCP. It provides AI assistants with comprehensive access to Gmail, Google Drive, Calendar, Docs, Sheets, Chat, Forms, Slides, Tasks, and Search with bidirectional sync capabilities.

Features

• 10 Google Services: Gmail, Drive, Calendar, Docs, Sheets, Chat, Forms, Slides, Tasks, Search
• 100+ Tools: Comprehensive API coverage for each service
• Advanced Sync Tools: Bidirectional file synchronization between local files and Google Drive (based on drive-synapsis)
• Search Aliases: Quick reference to search results using A-Z aliases
• OAuth 2.0/2.1: Secure authentication with persistent session management
• Session Persistence: Credentials survive server restarts - no re-authentication required
• Async Architecture: Non-blocking operations for high performance

Quick Start

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Node.js 18+ (only required for npx distribution usage)

Installation

# Clone the repository
cd google-workspace-mcp-advanced

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

Distribution Channels (npm/npx)

# Stable channel (npm latest)
npx -y google-workspace-mcp-advanced --transport stdio

# Prerelease channel (npm next)
npx -y google-workspace-mcp-advanced@next --transport stdio

# Pinned deterministic version (recommended for production rollouts)
npx -y google-workspace-mcp-advanced@1.0.0 --transport stdio

Notes:

• The npm launcher executes the matching Python release through uvx (or uv tool run fallback).
• Override Python package resolution with GWS_MCP_PYPI_SPEC, for example: GWS_MCP_PYPI_SPEC=google-workspace-mcp-advanced==1.0.0 npx -y google-workspace-mcp-advanced --transport stdio
• Release sequencing, provenance, and rollback guidance: docs/DISTRIBUTION_RELEASE.md.

Running the Server

# STDIO mode (default, for MCP clients)
uv run google-workspace-mcp-advanced --transport stdio

# HTTP mode (for web-based clients)
uv run google-workspace-mcp-advanced --transport streamable-http

# Single-user mode (bypasses session mapping)
uv run google-workspace-mcp-advanced --single-user

# Load specific services only
uv run google-workspace-mcp-advanced --tools gmail drive calendar

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, OpenCode):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-mcp-advanced", "--transport", "stdio"],
      "env": {
        "USER_GOOGLE_EMAIL": "[e-mail]"
      }
    },
    "google-workspace-dev": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/google-workspace-mcp-advanced",
        "google-workspace-mcp-advanced",
        "--transport",
        "stdio"
      ],
      "env": {
        "USER_GOOGLE_EMAIL": "[e-mail]"
      }
    }
  }
}

Use the npx server entry for stable releases and keep the uv run --project entry for local development.

User docs entry point: docs/INDEX.md. Contributor docs entry points: AGENTS.md and agent-docs/INDEX.md.

Authentication

This server uses OAuth 2.0/2.1 credentials. On first use:

1. The server will provide an OAuth URL
2. Open the URL in your browser
3. Sign in with your Google account
4. Grant the requested permissions
5. Credentials are stored in ~/.config/gws-mcp-advanced/credentials/

Environment Variables

Variable	Description	Default
USER_GOOGLE_EMAIL	Your Google email	Required
GOOGLE_OAUTH_CLIENT_ID	OAuth client ID	Required
GOOGLE_OAUTH_CLIENT_SECRET	OAuth client secret	Required
MCP_SINGLE_USER_MODE	Bypass session mapping	false
WORKSPACE_MCP_PORT	HTTP server port	9876
WORKSPACE_MCP_CONFIG_DIR	Directory for credentials	~/.config/gws-mcp-advanced
AUTH_DIAGNOSTICS	Enable auth debug logging	false
WORKSPACE_MCP_ALLOW_UNVERIFIED_JWT	Break-glass: allow identity extraction from unverified JWT claims (not recommended)	false

Available Tools

Gmail

• search_gmail_messages - Search emails
• get_gmail_message_content - Read email content
• send_gmail_message - Send emails
• draft_gmail_message - Create drafts
• And more...

Google Drive

• search_google_drive - Search files (results cached with A-Z aliases)
• read_google_drive_file - Read file content
• create_google_doc - Create documents
• upload_file - Upload files
• Sync Tools:
  • link_local_file - Link local file to Drive
  • update_google_doc - Upload local to Drive (dry-run default)
  • download_google_doc - Download Drive to local (dry-run default)
  • upload_folder - Recursive folder upload
  • mirror_drive_folder - Recursive folder download
  • download_doc_tabs - Multi-tab document sync

Google Calendar

• get_events - List calendar events
• create_event - Create events
• modify_event - Update events
• delete_event - Delete events

Google Docs

• get_document_outline - Get document structure
• read_document_section - Read specific sections
• append_to_google_doc - Append content
• replace_doc_text - Find and replace

Google Sheets

• read_sheet_range - Read cell ranges
• update_sheet_cell - Update cells
• create_sheet - Create spreadsheets
• append_to_sheet - Append rows

Google Chat

• list_spaces - List chat spaces
• get_messages - Read messages
• send_message - Send messages

Google Forms

• get_form - Get form details
• list_form_responses - List responses
• create_form - Create forms

Google Slides

• get_presentation - Get presentation details
• create_presentation - Create presentations
• batch_update_presentation - Update slides

Google Tasks

• list_tasks - List tasks
• create_task - Create tasks
• update_task - Update tasks

Google Search

• search_custom - Programmable Search Engine

Search Aliases

When you search Google Drive, results are automatically cached with aliases:

Search results:
[A] Project Plan - Google Doc
[B] Budget 2024 - Google Sheet
[C] Team Photo - Image

Use aliases in subsequent commands:

read_google_drive_file(file_id="A")  # Reads "Project Plan"

Sync Tools

The sync tools enable bidirectional synchronization between local files and Google Drive:

Linking Files

link_local_file(local_path="docs/notes.md", file_id="A")

Uploading Changes (Safe by Default)

# Dry run - shows diff without making changes
update_google_doc(local_path="docs/notes.md")

# Apply changes
update_google_doc(local_path="docs/notes.md", dry_run=False)

Downloading Changes (Safe by Default)

# Dry run - shows diff without making changes
download_google_doc(local_path="docs/notes.md")

# Apply changes
download_google_doc(local_path="docs/notes.md", dry_run=False)

Development

Project Structure

google-workspace-mcp-advanced/
├── auth/                 # OAuth and authentication
│   ├── google_auth.py    # Core auth logic
│   ├── google_oauth_config.py  # Embedded credentials
│   └── service_decorator.py # @require_google_service
├── core/                 # Shared utilities
│   ├── errors.py         # Custom error types
│   ├── managers.py       # SearchManager, SyncManager
│   └── server.py         # FastMCP server instance
├── gdrive/               # Google Drive tools
│   ├── drive_tools.py    # Core Drive tools
│   └── sync_tools.py     # Sync tools
├── gmail/                # Gmail tools
├── gcalendar/            # Calendar tools
├── gdocs/                # Docs tools
├── gsheets/              # Sheets tools
├── gchat/                # Chat tools
├── gforms/               # Forms tools
├── gslides/              # Slides tools
├── gtasks/               # Tasks tools
├── gsearch/              # Search tools
├── main.py               # CLI entry point
├── fastmcp_server.py     # FastMCP Cloud entry point
└── pyproject.toml        # Package configuration

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest tests/ --cov=.

# Run specific test file
uv run pytest tests/integration/test_auth_flow.py

Linting & Formatting

# Check linting
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Format code
uv run ruff format .

Recent Updates

v0.9.1 - Codebase Refactor

• Modular Architecture: Split monolithic tool files into domain-specific modules
• Improved Maintainability: Clearer separation of concerns for Gmail, Drive, and Docs
• Public API Preservation: Backward-compatible package structure
• Circular Dependency Fixes: Resolved import cycles in core/auth modules

v0.9.0 - Session Persistence & Auth Improvements

• Session persistence: Credentials now survive server restarts
• Atomic file writes: Prevents credential corruption on crash
• Credential recovery: Automatic recovery from file store on restart
• Auth diagnostics: Enable with AUTH_DIAGNOSTICS=1 for debugging
• 100+ tools: Expanded tool coverage across all services

v0.8.0 - Architecture Improvements

• Consolidated auth providers and middleware
• Added DI container and extended error hierarchy
• Improved single-user mode auto-recovery

License

MIT License.