Google Workspace MCP Server

A configurable Model Context Protocol (MCP) server that enables Claude to manage your Google Workspace services. Choose which services to enable - Calendar, Gmail, Docs, or any combination. Works with regular Gmail accounts - no Google Workspace subscription required!

🔧 User-Configurable Services

You control which Google services are enabled:

• ✅ Mix and match: Enable only Calendar + Docs, or Gmail only, etc.
• 🔒 Minimal permissions: Only request access to services you actually use
• 🔄 Easy changes: Reconfigure anytime with interactive tool
• 🛡️ Secure: No unnecessary broad permissions

Features

📅 Google Calendar

• Create events with enhanced day-of-week calculations
• 🎉 NEW: Smart holiday detection and scheduling
  • Automatically prevents scheduling on US and Canadian holidays
  • Suggests alternative working days when holidays detected
  • Optional force_holiday_booking parameter to override
• List calendars and events with computed day-of-week information
• Manage attendees and send invitations
• Search events by date or keywords
• Enhanced responses include accurate day-of-week, duration, and date calculations

✉️ Gmail

• Send emails with HTML support
• Search emails with Gmail's powerful query syntax
• Create drafts for later editing
• Support for CC/BCC recipients
• 🎯 NEW: Label-based access restriction
  • Optional filtering to restrict access to emails with specific label (e.g., "Jobs")
  • When enabled: search_emails filters automatically, send/draft operations blocked
  • Configurable via interactive setup or config/scopes.json

📄 Google Docs

• Create documents with initial content
• Update existing documents with new content
• Organize in Drive folders
• Share with collaborators

📊 Google Sheets (Not Implemented)

• Create spreadsheets with data
• Add headers and formatting
• Import data arrays

📽️ Google Slides (Not Implemented)

• Create presentations
• Add slides with different layouts
• Insert content

Security & Design Principles

🛡️ Safe-by-Design: Intentionally Limited Operations

This MCP server follows the principle of least privilege by intentionally excluding destructive operations:

✅ Supported Operations:

• Read: List calendars/events, search emails, view documents
• Create: New events, emails, drafts, documents
• Update: Modify existing documents
• Send: Send emails (with explicit user intent)

❌ Intentionally Excluded:

• Delete: No deletion of events, emails, or documents
• Trash: No moving items to trash
• Permanent removal: No irreversible data destruction

Why? This design provides an additional safety layer:

• Prevents accidental data loss through AI interaction
• Requires manual confirmation via Google UIs for destructive actions
• Aligns with security best practice: "AI can create and modify, humans confirm deletion"
• Reduces risk of unintended consequences from misunderstood prompts

Manual Cleanup: Test data created through the MCP server (calendar events, documents, emails) should be deleted manually through Google Calendar, Drive, or Gmail interfaces.

Quick Start

Prerequisites

• Python 3.11+
• Gmail account
• Google Cloud project (free)

Setup (~15 minutes, mostly the one-time Google Cloud config)

1. Clone and setup:

   git clone https://github.com/adamkwhite/google-workspace-mcp.git
   cd google-workspace-mcp
   ./scripts/setup.sh
   

2. Configure services (choose which to enable):

   python scripts/configure_scopes.py
   

3. Set up Google Cloud (the fiddly, one-time part). Everything below happens in the Google Cloud Console. Console labels shift occasionally, but the flow is stable:

   a. Create a project — use the project picker at the top bar (or select an existing one). It's free.

   b. Enable the APIs you'll use — APIs & Services → Enabled APIs & services → + Enable APIs and Services, then enable each that matches your config:

   • Google Calendar API (if Calendar enabled)
   • Gmail API (if Gmail enabled)
   • Google Docs API (if Docs enabled)
   • Google Drive API (required whenever Docs is enabled)

   c. Configure the OAuth consent screen — APIs & Services → OAuth consent screen:

   • User type: External
   • Provide an app name, your user support email, and a developer contact email. Everything else can stay blank.
   • You do not need to add scopes here — the server requests them at runtime from your scopes.json.

   d. Add yourself as a test user — in the consent screen's Audience / Test users section, add your own Gmail address. While the app is in Testing status, only listed test users can authenticate (this is the #1 cause of "Access blocked" errors).

   e. Create the OAuth client — APIs & Services → Credentials → + Create Credentials → OAuth client ID:

   • Application type: Desktop app
   • Create it, then Download JSON and save the file as config/credentials.json in the repo.

   Refresh-token note: while the app stays in Testing, Google expires refresh tokens after ~7 days, so you'd re-authenticate weekly. To avoid that, set the publishing status to In production (OAuth consent screen → Publish app). For personal, single-user use you can stay in production without going through Google's verification review.

4. Configure Claude Desktop: Add to your Claude Desktop config, replacing <ABSOLUTE_PATH_TO_REPO> with the absolute path to your clone (e.g., /home/you/Code/google-workspace-mcp). On Windows Claude Desktop with WSL:

   {
     "mcpServers": {
       "google-workspace": {
         "command": "wsl.exe",
         "args": [
           "-d", "Ubuntu",
           "bash", "-c",
           "cd <ABSOLUTE_PATH_TO_REPO> && source .venv/bin/activate && PYTHONPATH=<ABSOLUTE_PATH_TO_REPO>/src python src/server.py"
         ]
       }
     }
   }
   

   See config/claude_desktop_config.json for the template and config/claude_desktop_config_alternative.json for a bash-free alternative. On non-Windows hosts, drop the wsl.exe wrapper and call the venv Python directly.

5. First run opens a browser to grant access (only for enabled services). Because the OAuth app is your own and unverified, Google shows a "Google hasn't verified this app" screen — click Advanced → Go to <app name> (unsafe) and continue. This is expected; it's your app. The token is then cached in config/token.pickle and refreshed automatically.

🎯 Enhanced Calendar Features

Day-of-Week Accuracy

Calendar events now include computed fields that eliminate day-of-week calculation errors:

{
  "summary": "Team Meeting",
  "start": {"dateTime": "2025-09-27T14:00:00-04:00", "timeZone": "America/Toronto"},
  "end": {"dateTime": "2025-09-27T15:00:00-04:00", "timeZone": "America/Toronto"},
  "computed": {
    "startDay": "Saturday",
    "endDay": "Saturday",
    "startDate": "2025-09-27",
    "endDate": "2025-09-27",
    "duration": "1 hour",
    "spansMultipleDays": false
  }
}

Benefits:

• ✅ Accurate day-of-week - No more "Friday the 27th" when it's actually Saturday
• ⏰ Human-readable duration - "2 hours 30 minutes" instead of manual calculation
• 📅 Date consistency - Reliable YYYY-MM-DD format
• 🌐 Timezone-aware - Proper handling of EST, PST, UTC, and DST transitions

Usage Examples

Calendar Management

"Schedule a team meeting tomorrow at 2 PM for 1 hour with john@example.com and jane@example.com"
"Schedule a planning session next week" (automatically avoids holidays)
"Book a meeting on December 25th" (prompts: "This is Christmas. Continue? y/n")
"Show me all meetings this week with day-of-week information"
"List my calendar events for next Monday"
"Search for events with 'project review' in the title"

Email Operations

"Send an email to the team about the project update"
"Search for emails from John about the budget"
"Create a draft email for the monthly newsletter"
"Find all unread emails from this week"

Document Creation

"Create a meeting notes document for today's standup"
"Make a project proposal document and share it with sarah@example.com"
"Generate a report template in my Reports folder"

Integrated Workflows

"Schedule a project review meeting next Monday at 10 AM, create an agenda document, and email the invite to the team"
"Find all emails about Q4 planning and create a summary document"
"Create a presentation about our new feature and schedule a demo meeting"

🔧 Managing Service Configuration

Interactive Configuration

# Run the configuration wizard
python scripts/configure_scopes.py

The interactive tool helps you:

• ✅ See current configuration
• 🔧 Enable/disable services
• ⚠️ Handle dependencies automatically
• 🗑️ Clean up authentication tokens when needed

Manual Configuration

config/scopes.json is gitignored (it's your local config). Copy the template to create it, then edit — the server also falls back to sensible defaults if the file is absent:

cp config/scopes.example.json config/scopes.json

The template ships with a sample gmail_settings.restricted_label list (note _News Feed — multi-word labels are matched exactly and quoted automatically). Replace those with your own Gmail labels, or delete the gmail_settings block to leave Gmail unrestricted.

{
  "enabled_services": {
    "calendar": true,   # Enable Google Calendar
    "gmail": false,    # Disable Gmail
    "docs": true,      # Enable Google Docs
    "drive": true      # Auto-enabled (required for Docs)
  },
  "gmail_settings": {
    "restricted_label": "Jobs"  # Optional: Restrict Gmail to specific label
  }
}

Gmail Label Filtering

Restrict Gmail operations to emails with one or more specific labels:

Configuration (single label):

{
  "enabled_services": {
    "gmail": true
  },
  "gmail_settings": {
    "restricted_label": "Jobs"
  }
}

Configuration (multiple labels — reads from any of them):

{
  "gmail_settings": {
    "restricted_label": ["Jobs", "_News Feed", "AI"]
  }
}

Label names must match Gmail exactly (case-sensitive, including leading underscores and spaces). Multiple labels are combined with OR, so search_emails returns mail carrying any one of them. The interactive configure_scopes.py wizard only sets a single label — for a list, edit config/scopes.json directly.

Behavior:

• ✅ search_emails: Automatically filters to only show emails with the configured label(s)
• 🚫 send_email: Blocked with clear error message
• 🚫 create_email_draft: Blocked with clear error message

Use Cases:

• Job search: Only access emails related to job applications
• Client communications: Restrict to specific client label
• Privacy: Limit AI access to subset of emails

Setup:

1. Create label in Gmail (e.g., "Jobs")
2. Run python scripts/configure_scopes.py and enable Gmail label filtering
3. Or manually add gmail_settings to config/scopes.json
4. Restart MCP server

Checking Configuration

In Claude, use: get_mcp_configuration to see:

• Which services are enabled
• Required API scopes
• Configuration errors
• Available tools

Available Tools (Conditional)

Note: Only tools for enabled services are available

Configuration Tools (Always Available)

• get_mcp_configuration - Show current service configuration

Calendar Tools (if enabled)

• create_calendar_event - Create new events with computed day-of-week fields
• list_calendars - Show all available calendars
• list_calendar_events - Search and list events with enhanced date information

Gmail Tools (if enabled)

• send_email - Send emails with HTML support
• search_emails - Search with Gmail query syntax
• create_email_draft - Save drafts for later

Document Tools (if enabled)

• create_google_doc - Create documents with content
• update_google_doc - Add content to existing documents

Project Structure

google-workspace-mcp/
├── config/
│   ├── scopes.example.json # Template — copy to scopes.json
│   ├── scopes.json        # Your service config (gitignored, user-editable)
│   ├── credentials.json   # OAuth2 credentials from Google
│   └── token.pickle      # Cached authentication token
├── src/                    # Application source code
│   ├── server.py          # Main MCP server (conditional tool registration)
│   ├── utils/
│   │   ├── scope_manager.py # Service configuration management
│   │   └── date_helpers.py  # Enhanced timezone-aware date calculations
│   ├── auth/
│   │   └── google_auth.py # Dynamic authentication
│   └── tools/             # Service-specific implementations
│       ├── calendar.py    # Calendar operations
│       ├── gmail.py       # Email operations
│       └── docs.py        # Document creation
├── scripts/
│   └── configure_scopes.py # Interactive configuration tool
├── tests/                 # Unit tests
├── docs/                  # Documentation
├── scripts/               # Setup and deployment
└── config/                # Configuration files

Security

• OAuth2 authentication with secure token storage
• User-configurable service permissions - Enable only Calendar, Gmail, Docs, or any combination
• Minimal scope requests based on enabled services:
  • Calendar: https://www.googleapis.com/auth/calendar (if enabled)
  • Gmail: https://www.googleapis.com/auth/gmail.modify (if enabled)
  • Docs: https://www.googleapis.com/auth/documents, https://www.googleapis.com/auth/drive.file (if enabled)
• Tokens stored locally, never transmitted
• Automatic token refresh
• All credentials in .gitignore

API Quotas (Free Tier)

All quotas are per-user and more than sufficient for personal use:

• Calendar API: 1,000,000 queries/day
• Gmail API: 250 quota units/user/second
• Docs API: 300 requests/minute
• Sheets API: 300 requests/minute
• Slides API: 300 requests/minute
• Drive API: 1,000 requests/100 seconds

Development

# Activate virtual environment
source .venv/bin/activate

# Run tests
pytest tests/

# Run server manually
python src/server.py

# Format code
black src/

Troubleshooting

Authentication Issues

• "Access blocked: app not verified" / "app is being tested" — your Gmail isn't listed as a test user. Add it under OAuth consent screen → Test users, or publish the app (see Setup step 3d).
• Re-prompted to log in every ~7 days — the app is still in Testing; testing-mode refresh tokens expire weekly. Set publishing status to In production to stop this (Setup step 3).
• Delete config/token.pickle and re-authenticate
• Verify all APIs are enabled in Google Cloud Console
• Check config/credentials.json exists and is valid

Permission Errors

• Ensure all required scopes are included
• Re-authenticate after adding new scopes
• Check API quotas haven't been exceeded

Tool Errors

• Use list_calendars to get correct calendar IDs
• Verify email addresses are valid
• Check datetime formats (ISO 8601)

Roadmap

• [x] Calendar integration with computed date fields
• [x] Gmail integration (send, search, drafts)
• [x] Google Docs creation and updates
• [x] User-configurable service scoping
• [ ] Calendar event updates and deletion
• [ ] Google Sheets with data import
• [ ] Google Slides with templates
• [ ] Batch operations
• [ ] Advanced search features
• [ ] File attachments

Contributing

See todo.md for current tasks and priorities.

License

MIT