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

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