Google Workspace MCP Server

A Model Context Protocol server for seamless integration between Claude Code and Google Workspace services.

Features

✅ Complete Google Workspace Integration

• Google Drive: Full file management (search, read, create, update, delete, upload/download)

• Google Docs: Document creation, reading, and editing

• Google Sheets: Spreadsheet operations with range updates and batch processing

• Google Slides: Presentation management and slide manipulation

• Google Forms: Form creation, editing, and response collection

• Gmail: Email search, read, send, reply, and label management

🔒 Secure Authentication

• OAuth 2.0 authentication with automatic token refresh

• Encrypted token storage

• Minimal scope requirements

⚡ Performance Optimized

• Async/await architecture for concurrent operations

• Built-in caching with TTL

• Smart rate limiting to prevent API quota exhaustion

• Request batching where possible

🛡️ Robust Error Handling

• Comprehensive error management

• Automatic retry logic for transient failures

• Detailed error messages for debugging

Related MCP server: Ultimate Google Docs & Drive MCP Server

Installation

Prerequisites

• Python 3.10 or higher

• Google Cloud Project with Workspace APIs enabled

• OAuth 2.0 credentials

Step 1: Clone and Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/google-workspace-mcp.git
cd google-workspace-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Create config directory
mkdir -p config

Step 2: Google Cloud Console Setup

1. Go to Google Cloud Console

2. Create a new project or select existing one

3. Enable the following APIs:

   • Google Drive API

   • Google Docs API

   • Google Sheets API

   • Google Slides API

   • Google Forms API

   • Gmail API

4. Configure OAuth Consent Screen:

   • Go to "APIs & Services" > "OAuth consent screen"

   • Choose "External" user type

   • Fill in required fields (App name, User support email, Developer contact)

   • Add scopes:

     • https://www.googleapis.com/auth/drive

     • https://www.googleapis.com/auth/documents

     • https://www.googleapis.com/auth/spreadsheets

     • https://www.googleapis.com/auth/presentations

     • https://www.googleapis.com/auth/forms

     • https://www.googleapis.com/auth/gmail.modify

5. Create OAuth 2.0 Client ID:

   • Go to "Credentials" > "Create Credentials" > "OAuth client ID"

   • Choose "Desktop app" as application type

   • Download credentials JSON file

   • Copy config/credentials.json.example to config/credentials.json

   • Replace the example values with your downloaded credentials

Step 3: Initial Authentication

# Run server for first-time authentication
python3 -m google_workspace_mcp

# Browser will open for OAuth consent
# Grant necessary permissions
# Token will be saved automatically

Step 4: Claude Code Integration

Add to your Claude Code MCP settings (~/.claude/config/settings.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "/usr/local/bin/python3",
      "args": ["-m", "google_workspace_mcp"],
      "cwd": "/path/to/your/google-workspace-mcp",
      "env": {}
    }
  }
}

Note: Replace /path/to/your/google-workspace-mcp with your actual installation path.

Available Tools

Google Drive (8 tools)

• drive_search_files - Search files/folders

• drive_read_file - Read file content

• drive_create_file - Create new file

• drive_update_file - Update existing file

• drive_delete_file - Delete file

• drive_upload_file - Upload local file

• drive_download_file - Download to local

• drive_list_shared_drives - List Team Drives

Google Docs (4 tools)

• docs_create - Create document

• docs_read - Read document

• docs_update - Update document

• docs_delete - Delete document

Google Sheets (4 tools)

• sheets_create - Create spreadsheet

• sheets_read - Read range

• sheets_update - Update range

• sheets_delete - Delete spreadsheet

Google Slides (4 tools)

• slides_create - Create presentation

• slides_read - Read presentation

• slides_update - Update slides

• slides_delete - Delete presentation

Google Forms (5 tools)

• forms_create - Create form

• forms_read - Read form structure

• forms_update - Update form

• forms_delete - Delete form

• forms_get_responses - Get form responses

Gmail (6 tools)

• gmail_search_messages - Search emails

• gmail_read_message - Read email content

• gmail_send_message - Send new email

• gmail_reply_message - Reply to email

• gmail_delete_message - Delete email

• gmail_list_labels - List labels

Usage Examples

Search Drive Files

In Claude Code:
"Search my Drive for files named 'project report'"

Uses: drive_search_files with query parameter

Read and Summarize Document

"Read the document with ID xyz and summarize it"

Uses: drive_read_file → Processes content

Send Email

"Send an email to team@example.com with subject 'Meeting Update' and body '...'"

Uses: gmail_send_message

Create Spreadsheet

"Create a new spreadsheet called 'Q4 Budget' with headers A1:E1"

Uses: sheets_create → sheets_update

Configuration

Environment Variables

# Optional: Custom config directory
export GW_MCP_CONFIG_DIR=~/.config/gw-mcp

# Optional: Log level
export GW_MCP_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

Cache Settings

Default cache TTL: 300 seconds (5 minutes) Max cache size: 1000 items

Rate Limiting

Default limits:

• 100 requests per 60 seconds per service

• Burst limit: 10 consecutive requests

Troubleshooting

Authentication Issues

# Clear stored tokens
rm ~/.config/gw-mcp/token.pickle

# Re-authenticate
python3 -m google_workspace_mcp

Permission Errors

• Verify all required APIs are enabled in Google Cloud Console

• Check OAuth scopes in consent screen configuration

• Ensure credentials.json is in correct location

Rate Limit Errors

• Server automatically handles rate limiting with exponential backoff

• Check Google Cloud Console quotas if persistent issues

Import Errors

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Development

Running Tests

pytest tests/
pytest tests/ --cov=src --cov-report=html

Project Structure

google-workspace-mcp/
├── src/
│   ├── auth/           # OAuth authentication
│   ├── services/       # Google API wrappers
│   ├── tools/          # MCP tool definitions
│   ├── utils/          # Utilities (logging, caching, etc.)
│   └── server.py       # Main MCP server
├── config/             # Configuration files
├── tests/              # Test suite
├── requirements.txt    # Dependencies
├── setup.py           # Package setup
└── README.md          # This file

Architecture

Claude Code (MCP Client)
        ↓
MCP Protocol (stdio)
        ↓
Google Workspace MCP Server
  ├── MCP Handler (Tool Registry)
  ├── Service Layer (API Wrappers)
  │   ├── Drive Service
  │   ├── Docs Service
  │   ├── Sheets Service
  │   ├── Slides Service
  │   ├── Forms Service
  │   └── Gmail Service
  ├── Auth Manager (OAuth 2.0)
  └── Infrastructure (Cache, Rate Limit, Logging)
        ↓
Google Workspace APIs

Security Considerations

• Token Storage: Tokens encrypted and stored securely in user config directory

• Scope Minimization: Only requests necessary permissions

• No Credential Logging: Sensitive data never logged

• Automatic Token Refresh: Expired tokens refreshed automatically

• Rate Limiting: Prevents quota exhaustion and API abuse

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Open an issue on GitHub

• Check troubleshooting section

• Review Google Workspace API documentation

Acknowledgments

• Built with MCP Python SDK

• Uses Google API Python Client

• Designed for Claude Code