Google Workspace MCP Server

Connect Claude to Google Workspace APIs through the Model Context Protocol (MCP).

Features

116 MCP tools across 7 Google Workspace APIs:

Service	Tools	Capabilities
Gmail	27	Search, send, reply, drafts, labels, filters, formatting, batch operations, attachments
Calendar	8	List calendars, create/update/delete events, manage attendees, free/busy
Drive	17	Search, upload/download binary files, folders, permissions, sync (rclone integration)
Docs	17	Create, edit, format text/paragraphs, tables, lists, tabs, comments
Sheets	12	Create, read, write, format cells, charts, merge, conditional formatting
Slides	21	Create presentations, slides, format text, backgrounds, layouts
Tasks	13	Task lists, create/update/complete tasks, subtasks, search

Highlights

Full Gmail Management: Search with advanced queries, send/reply with file attachments, organize with labels, filters, rich HTML formatting, batch operations
Binary File Transfer: Upload any file type to Drive via local path; download Drive files and Gmail attachments to disk
Calendar Integration: Create events with attendees, manage multiple calendars, handle timezones, check availability
Drive Operations: Search files, manage folders, permissions, upload/download with optional rclone sync
Google Docs: Create and edit documents, rich text formatting, tables, lists, tabs, comments, Mermaid diagrams
Google Sheets: Create spreadsheets, format cells, charts, conditional formatting, merge cells, number formats
Google Slides: Create presentations, format text, add images/text boxes, backgrounds, layouts, bullet lists
Tasks API: Full task management with lists, subtasks, due dates, and cross-list search

Binary File Transfer (v0.3.0)

Work with any file type — not just text:

# Upload a JPEG to Drive
upload_drive_file(local_path="/path/to/photo.jpg", parent_id="<folder-id>")

# Download a Drive file to disk (PDF, image, etc.)
get_drive_file_content(file_id="<id>", save_path="/tmp/report.pdf")

# Send an email with attachments
send_email(to="...", subject="...", body="...", attachments=["/path/to/file.pdf"])

# List attachments in a received email
get_gmail_message_content(message_id="<id>")
# → response includes: attachments: [{filename, mimeType, size, attachmentId}, ...]

# Download a Gmail attachment
download_gmail_attachment(message_id="<id>", attachment_id="<att-id>", save_path="/tmp/file.pdf")

Formatting Capabilities

Rich Text Formatting: Apply bold, italic, underline, colors, fonts across Docs, Slides, and Gmail
Advanced Cell Formatting: Background colors, borders, number formats, conditional formatting in Sheets
Professional Presentations: Custom layouts, formatted text boxes, backgrounds, and bullet lists in Slides
HTML Email Creation: Rich formatting for professional email communications

Installation

pip install gworkspace-mcp

Or with uv:

uv pip install gworkspace-mcp

For development:

git clone https://github.com/masapasa/google-workspace-mcp.git
cd google-workspace-mcp
pip install -e ".[dev]"

Quick Start

1. Set Up Google Cloud Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Enable the following APIs:
- Gmail API
- Google Calendar API
- Google Drive API
- Google Docs API
- Google Sheets API
- Google Slides API
- Google Tasks API
Create OAuth 2.0 credentials (Desktop application)
Download and note your Client ID and Client Secret

2. Authenticate

# Set your credentials
export GOOGLE_OAUTH_CLIENT_ID='your-client-id'
export GOOGLE_OAUTH_CLIENT_SECRET='your-client-secret'  # pragma: allowlist secret

# Run OAuth flow (opens browser)
workspace setup

# Verify authentication
workspace doctor

3. Start MCP Server

workspace mcp

4. Connect to Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "workspace",
      "args": ["mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"  // pragma: allowlist secret
      }
    }
  }
}

Restart Claude Desktop to activate.

Multi-Account Support

Multiple Google accounts can be configured as named profiles, letting you switch between personal and work accounts without re-authenticating.

Setting Up Multiple Accounts

# Set up a named profile (opens browser for each account)
workspace setup --account personal@gmail.com
workspace setup --account work@company.com

# List all configured profiles
workspace accounts list

# Switch the default profile
workspace accounts default work@company.com

# Remove a profile
workspace accounts remove personal@gmail.com

# Check authentication status for a specific account
workspace doctor --account work@company.com

Using Accounts Per Tool Call

Every MCP tool accepts an optional account parameter:

search_gmail_messages(query="budget", account="work@company.com")
get_events(calendar_id="primary", account="personal@gmail.com")

Account Resolution Order

When account is not specified, the server selects the account in this order:

account parameter in the tool call (explicit, highest priority)
GWORKSPACE_ACCOUNT environment variable (session-wide override)
Default profile set via workspace accounts default
Fallback to "gworkspace-mcp" (backward compatible with existing tokens)

Session-Wide Account Override

Set GWORKSPACE_ACCOUNT to make all tool calls in a session use a specific account without passing account each time:

export GWORKSPACE_ACCOUNT=work@company.com
workspace mcp

Listing Configured Accounts

The list_accounts MCP tool returns all configured profiles:

list_accounts()
# → [{email, is_default, created_at}, ...]

Storage Format

All profiles are stored in ~/.gworkspace-mcp/tokens.json. The format is backward compatible — existing single-account tokens continue to work without any changes:

{
  "gworkspace-mcp": { ... },
  "work@company.com": { ... },
  "personal@gmail.com": { ... }
}

Authentication

OAuth 2.0 Flow

This server uses OAuth 2.0 for secure authentication with Google APIs. The authentication flow:

workspace setup opens your browser for Google consent
You authorize access to Gmail, Calendar, Drive, Docs, Sheets, Slides, and Tasks
Tokens are securely stored locally
Tokens auto-refresh when expired

Required Scopes

The server requests the following OAuth scopes:

Scope	Purpose
`https://www.googleapis.com/auth/gmail.modify`	Read, send, and organize Gmail
`https://www.googleapis.com/auth/calendar`	Full calendar access
`https://www.googleapis.com/auth/drive`	Full Drive access
`https://www.googleapis.com/auth/documents`	Read and write Google Docs
`https://www.googleapis.com/auth/spreadsheets`	Read and write Google Sheets
`https://www.googleapis.com/auth/presentations`	Read and write Google Slides
`https://www.googleapis.com/auth/tasks`	Full Tasks access

Token Storage

Tokens are stored at: ~/.gworkspace-mcp/tokens.json

This file contains your OAuth tokens. Keep it secure and do not share it.

Available Tools

Gmail (26 tools)

Tool	Description
`search_gmail_messages`	Search messages with Gmail query syntax
`get_gmail_message_content`	Get full message content by ID
`send_email`	Send a new email
`reply_to_email`	Reply to an existing thread
`create_draft`	Save email as draft
`list_gmail_labels`	List all labels (system and custom)
`create_gmail_label`	Create a custom label
`delete_gmail_label`	Delete a custom label
`modify_gmail_message`	Add/remove labels from a message
`archive_gmail_message`	Archive a message (remove from inbox)
`trash_gmail_message`	Move message to trash
`untrash_gmail_message`	Restore message from trash
`mark_gmail_as_read`	Mark message as read
`mark_gmail_as_unread`	Mark message as unread
`star_gmail_message`	Add star to message
`unstar_gmail_message`	Remove star from message
`batch_modify_gmail_messages`	Bulk add/remove labels
`batch_archive_gmail_messages`	Bulk archive messages
`batch_trash_gmail_messages`	Bulk trash messages
`batch_mark_gmail_as_read`	Bulk mark as read
`batch_delete_gmail_messages`	Permanently delete messages (caution!)
`format_email_content`	Format email content with HTML styling
`set_email_signature`	Set Gmail signature with formatting
`create_formatted_email`	Create rich HTML emails with formatting
`list_gmail_filters`	List all Gmail filters
`create_gmail_filter`	Create new Gmail filter
`delete_gmail_filter`	Delete Gmail filter
`get_vacation_settings`	Get vacation auto-responder settings
`set_vacation_settings`	Configure vacation auto-responder

Calendar (8 tools)

Tool	Description
`list_calendars`	List all accessible calendars
`create_calendar`	Create a new calendar
`update_calendar`	Update calendar properties
`delete_calendar`	Delete a calendar
`get_events`	Get events within a time range
`create_event`	Create a new event
`update_event`	Update an existing event
`delete_event`	Delete an event
`query_free_busy`	Check availability for attendees

Drive (17 tools)

Tool	Description
`search_drive_files`	Search files with Drive query syntax
`get_drive_file_content`	Get file content (text files)
`create_drive_folder`	Create a new folder
`upload_drive_file`	Upload a text file
`delete_drive_file`	Delete a file or folder
`move_drive_file`	Move file to different folder
`list_drive_contents`*	List folder contents
`download_drive_folder`*	Download folder to local filesystem
`upload_to_drive`*	Upload local folder to Drive
`sync_drive_folder`*	Sync between local and Drive

*Requires rclone to be installed

Sheets (12 tools)

Tool	Description
`create_spreadsheet`	Create a new Google Spreadsheet
`get_spreadsheet_data`	Get spreadsheet metadata and structure
`list_spreadsheet_sheets`	List all sheets in a spreadsheet
`get_sheet_values`	Get values from a specific sheet/range
`update_sheet_values`	Update specific cells with new values
`append_sheet_values`	Append rows to end of sheet data
`clear_sheet_values`	Clear values from a range
`format_cells`	Apply formatting (colors, fonts, borders)
`set_number_format`	Set number formats (currency, percentage, date)
`merge_cells`	Merge cells across ranges
`set_column_width`	Adjust column widths
`create_chart`	Create charts (bar, line, pie) from data

Slides (21 tools)

Tool	Description
`create_presentation`	Create a new Google Slides presentation
`get_presentation`	Get presentation metadata and structure
`list_presentations`	List accessible presentations
`get_presentation_text`	Extract all text from presentation
`get_slide`	Get specific slide content
`add_slide`	Add new slide with layout
`delete_slide`	Delete a slide
`update_slide_text`	Update text in slide shapes
`format_text_in_slide`	Apply text formatting to slide content
`add_formatted_text_box`	Add text box with custom formatting
`add_text_box`	Add basic text box to slide
`set_slide_background`	Set slide background color or image
`create_bulleted_list_slide`	Create slide with bulleted list
`apply_slide_layout`	Apply predefined layout to slide
`add_image`	Add image from URL to slide

Docs (17 tools)

Tool	Description
`create_document`	Create a new Google Doc
`get_document`	Get document content and structure
`append_to_document`	Append text to a document
`upload_markdown_as_doc`	Convert Markdown to Google Doc
`list_document_comments`	List all comments on a document
`add_document_comment`	Add a comment to a document
`reply_to_comment`	Reply to an existing comment
`list_document_tabs`	List all tabs in a document
`get_tab_content`	Get content from a specific tab
`create_document_tab`	Create a new tab
`update_tab_properties`	Update tab title or icon
`move_tab`	Move tab to new position
`render_mermaid_to_doc`	Render Mermaid diagram and insert into doc
`format_text_in_document`	Apply text formatting (bold, italic, colors, fonts)
`format_paragraph_in_document`	Apply paragraph formatting (alignment, spacing)
`create_list_in_document`	Create bulleted or numbered lists
`insert_table_in_document`	Insert tables with custom dimensions
`apply_heading_style`	Apply heading styles (H1, H2, etc.)
`set_document_margins`	Configure document margins
`publish_markdown_to_doc`	Publish markdown content as Google Doc

Accounts (1 tool)

Tool	Description
`list_accounts`	List all configured profiles with email, is_default, and created_at

Tasks (13 tools)

Tool	Description
`list_task_lists`	List all task lists
`get_task_list`	Get a specific task list
`create_task_list`	Create a new task list
`update_task_list`	Update task list title
`delete_task_list`	Delete a task list
`list_tasks`	List tasks in a list
`get_task`	Get a specific task
`search_tasks`	Search tasks across all lists
`create_task`	Create a new task
`update_task`	Update task details
`complete_task`	Mark task as completed
`delete_task`	Delete a task
`move_task`	Move task or make it a subtask

CLI Commands

# Authenticate with Google (default profile)
workspace setup

# Authenticate a named profile
workspace setup --account NAME

# Check authentication status and dependencies
workspace doctor

# Check status for a specific account
workspace doctor --account NAME

# Manage named profiles
workspace accounts list          # show all profiles with default marker
workspace accounts default NAME  # switch the default profile
workspace accounts remove NAME   # remove a profile

# Start the MCP server (for Claude Desktop)
workspace mcp

# Show version
workspace --version

# Show help
workspace --help

Documentation

For detailed documentation, see the docs/ directory:

Getting Started - Installation, authentication, quickstart
User Guides - Claude Desktop integration, CLI reference
API Reference - Complete tool documentation for all 116 tools
Development - Contributing, testing, releasing

Development

# Clone and install
git clone https://github.com/masapasa/google-workspace-mcp.git
cd google-workspace-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Code quality
ruff format src tests && ruff check src tests && mypy src

See Contributing Guide for full development setup.

Requirements

Python: 3.10 or higher
Google Cloud Project: With Workspace APIs enabled
OAuth 2.0 Credentials: Desktop application type
Optional: rclone for Drive sync features (4 tools)
Optional: pandoc for Markdown to Docs conversion
Optional: @mermaid-js/mermaid-cli for Mermaid diagrams

Troubleshooting

"Not authenticated" error

Run workspace setup to authenticate, or check status with workspace doctor.

Token refresh failing

Delete ~/.gworkspace-mcp/tokens.json and run workspace setup again.

Missing rclone tools

The 4 rclone-based tools (list_drive_contents, download_drive_folder, upload_to_drive, sync_drive_folder) require rclone to be installed. Install from rclone.org.

Claude Desktop not seeing tools

Ensure the config file path is correct for your OS
Restart Claude Desktop after config changes
Check that workspace mcp runs without errors

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

Links

Repository: https://github.com/masapasa/google-workspace-mcp
Issues: https://github.com/masapasa/google-workspace-mcp/issues
PyPI: https://pypi.org/project/gworkspace-mcp/

Acknowledgments

Extracted from claude-mpm - Multi-agent project manager with MCP server integrations.

Name		Name	Last commit message	Last commit date
.ai-trackdown		.ai-trackdown
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/gworkspace_mcp		src/gworkspace_mcp
tests		tests
tickets/issues		tickets/issues
.env.local.example		.env.local.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
BUILD_NUMBER		BUILD_NUMBER
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
UNIFIED_PUBLISHING_SUMMARY.md		UNIFIED_PUBLISHING_SUMMARY.md
VERSION		VERSION
mypy.ini		mypy.ini
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation