Claude Code skill for managing Google Calendar and Gmail through Python code execution.
google-workspace/ # Deploy this folder to ~/.claude/skills/
├── SKILL.md # Core skill instructions for Claude
├── scripts/
│ └── unified_auth.py # OAuth authentication tool
└── references/ # Detailed API documentation
├── calendar-api.md # Google Calendar API reference
└── gmail-api.md # Gmail API reference
Key Principle: Data processing happens in sandbox (Python execution), not in Claude's context. This reduces token consumption significantly.
cp -r google-workspace ~/.claude/skills/mkdir -p ~/.google-workspace
python3 -m venv ~/.google-workspace/venv
source ~/.google-workspace/venv/bin/activate
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client
deactivate- Visit Google Cloud Console
- Create or select a project
- Enable Google Calendar API and Gmail API
- Navigate to: APIs & Services → Credentials → Create Credentials
- Choose OAuth 2.0 Client ID → Desktop application
- Download the credentials JSON file
- Save it as
~/.google-workspace/credentials.json
cd ~/.claude/skills/google-workspace
source ~/.google-workspace/venv/bin/activate
python3 scripts/unified_auth.pyThe script will:
- Automatically open your browser for OAuth authorization
- Save the access token to
~/.google-workspace/token.json - Test both Calendar and Gmail API connections
- Display success confirmation
First-time only: Click "Allow" in the browser when prompted.
Once deployed, Claude Code automatically uses this skill when you mention calendars or emails:
"Show me this week's meetings"
"What's on my calendar for tomorrow?"
"Create a meeting with John at 3pm tomorrow"
"List all my calendars"
"What unread emails do I have?"
"Send an email to john@example.com"
"Search for emails from Sarah about project"
"Archive all emails from newsletter@example.com"
"Generate a weekly report and email it to my manager"
"Find all meeting invites in my inbox and add them to calendar"
User request → MCP tool call → Full JSON response (6000+ tokens)
→ Data enters context → Process in context → Output
User request → Claude writes Python code (~200 tokens)
→ Execute in sandbox → Process data locally
→ Return summary only (~300 tokens) → Output
Result: ~94% token savings on typical operations.
- List: Get events from all calendars, specific date ranges
- Create: Add new events with attendees, reminders
- Update: Modify existing events
- Delete: Remove events
- Utilities: Check free/busy status, list available colors
- Multi-calendar: Automatically queries all user calendars
- Send: Compose and send emails (plain text or HTML)
- Search: Use Gmail query syntax for powerful searches
- Read: Fetch email content with metadata
- Batch: Modify/delete multiple emails efficiently
- Labels: Create, update, and manage labels
- Drafts: Create and manage draft emails
- Environment Detection: Automatically checks and creates venv if missing
- Token Management: Auto-refresh expired tokens
- Error Handling: Graceful fallbacks for API errors
- Zero Configuration: No environment variables required
All runtime files are stored in ~/.google-workspace/:
~/.google-workspace/
├── venv/ # Python virtual environment
├── token.json # OAuth access token (auto-refreshed)
└── credentials.json # OAuth client credentials
Tokens expire after ~7 days. When you see authentication errors:
cd ~/.claude/skills/google-workspace
source ~/.google-workspace/venv/bin/activate
python3 scripts/unified_auth.pyThe script will guide you through re-authorization.
- Token files have
600permissions (owner read/write only) - Never commit
credentials.jsonortoken.jsonto git - Credentials are stored locally, not in cloud
- OAuth uses industry-standard security practices
Detailed API documentation is available in the references/ directory:
- Calendar API Reference: Event properties, time formats, query parameters
- Gmail API Reference: Message formats, query syntax, batch operations
These are loaded by Claude only when needed (progressive disclosure).
Install dependencies in the virtual environment:
source ~/.google-workspace/venv/bin/activate
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-clientRe-run the authentication script:
python3 ~/.claude/skills/google-workspace/scripts/unified_auth.pyEnable required APIs in Google Cloud Console:
- Visit API Library
- Search for "Google Calendar API" and "Gmail API"
- Click "Enable" for each
Claude generates Python code following this template:
source ~/.google-workspace/venv/bin/activate && python3 << 'EOF'
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
# Load credentials
token_path = '~/.google-workspace/token.json'
creds = Credentials.from_authorized_user_file(token_path)
# Build service
calendar = build('calendar', 'v3', credentials=creds)
# Query and process data in sandbox
events = calendar.events().list(...).execute()
# ... filter, sort, aggregate ...
# Return only summary
print(f"Found {len(events)} events")
EOFThe skill automatically queries all user calendars, not just the primary calendar:
calendars = calendar.calendarList().list().execute()['items']
for cal in calendars:
events = calendar.events().list(calendarId=cal['id'], ...).execute()
# Process events from each calendarThis skill consolidates functionality from:
- @cocal/google-calendar-mcp - Calendar operations
- @gongrzhe/server-gmail-autoauth-mcp - Gmail auto-authentication
MIT
Issues and pull requests are welcome! Please ensure:
- Code follows existing patterns
- Python code is executed in sandbox (not imported)
- Documentation is updated for new features
