Google Workspace MCP Server
bobmatnyc/gworkspace-mcp
Conecte Claude ao Google Workspace com 116 ferramentas MCP
Ver no GitHubServidor MCP que conecta Claude aos serviços do Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides e Tasks) via Model Context Protocol. Oferece 116 ferramentas para automação completa de fluxos de trabalho, incluindo transferência de arquivos binários, gerenciamento de emails com anexos e operações em documentos, planilhas e apresentações.
Instalação
npx convez-ai bobmatnyc/gworkspace-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de gerenciamento de emails e anexos no Gmail
- Criação e edição programática de documentos, planilhas e apresentações
- Sincronização e busca de arquivos no Google Drive
- Agendamento e gestão de eventos no Google Calendar
- Gerenciamento de tarefas e listas de verificação
Veredito

Integração madura e abrangente do Google Workspace com suporte robusto a transferência de arquivos binários e 116 ferramentas cobrindo toda a suite. Excelente para automação de workflows empresariais, embora requeira configuração OAuth adequada.
README
A tradução para o português deste README ainda está na fila.
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:
accountparameter in the tool call (explicit, highest priority)GWORKSPACE_ACCOUNTenvironment 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 setupopens 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 mcpruns 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.