| name | google-workspace |
| description | Connect to Gmail and Google Calendar via OAuth 2.0. Use when users want to search/read emails, create drafts, search calendar events, check availability, or schedule meetings. Triggers on queries about email, inbox, calendar, schedule, or meetings. |
| license | MIT |
Google Workspace Integration
Gmail and Google Calendar access via shared OAuth 2.0 authentication.
Prerequisites
- Python 3.10+ available
- Google Cloud project with Gmail API and Calendar API enabled
- OAuth 2.0 credentials (
credentials.json) downloaded
- Required packages:
google-api-python-client, google-auth-httplib2, google-auth-oauthlib
OAuth Setup
Step 1: Create Google Cloud Project
- Go to https://console.cloud.google.com/
- Create a new project or select existing
- Navigate to APIs & Services → Library
- Enable both Gmail API and Google Calendar API
Step 2: Configure OAuth Consent Screen
- Go to APIs & Services → OAuth consent screen
- Select External user type
- Add scopes:
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar.events
- Add user's email as a test user
Step 3: Create OAuth Credentials
- Go to APIs & Services → Credentials
- Click Create Credentials → OAuth client ID
- Select Desktop app as application type
- Download JSON and rename to
credentials.json
Step 4: Install Dependencies
uv add google-api-python-client google-auth-httplib2 google-auth-oauthlib
Step 5: First Authentication
Run any script - it will open a browser for OAuth consent. A token.json is saved for future use.
Gmail Operations
Search Emails
uv run python tools/google-workspace/scripts/search_emails.py "from:someone@example.com" --credentials ./credentials.json
Read Email Content
uv run python tools/google-workspace/scripts/read_email.py <message_id> --credentials ./credentials.json
Create Draft
uv run python tools/google-workspace/scripts/create_draft.py \
--to "recipient@example.com" \
--subject "Subject line" \
--body "Email body" \
--credentials ./credentials.json
Find Emails Needing Reply
uv run python tools/google-workspace/scripts/needs_reply.py --credentials ./credentials.json
Calendar Operations
List Calendars
uv run python tools/google-workspace/scripts/list_calendars.py --credentials ./credentials.json
Search Events
uv run python tools/google-workspace/scripts/search_events.py "meeting" --credentials ./credentials.json
uv run python tools/google-workspace/scripts/search_events.py --start "2024-01-15" --end "2024-01-20" --credentials ./credentials.json
Check Availability
uv run python tools/google-workspace/scripts/find_busy.py \
--start "2024-01-15T09:00:00" \
--end "2024-01-15T17:00:00" \
--credentials ./credentials.json
Create Event
uv run python tools/google-workspace/scripts/create_event.py \
--summary "Team Meeting" \
--start "2024-01-15T10:00:00" \
--end "2024-01-15T11:00:00" \
--attendees "alice@example.com,bob@example.com" \
--credentials ./credentials.json
Options: --description, --location, --timezone, --calendar
Scripts Reference
Gmail:
gmail_auth.py - Gmail authentication utilities
search_emails.py - Search inbox with Gmail query syntax
read_email.py - Read email content by message ID
create_draft.py - Create draft emails
needs_reply.py - Find emails awaiting response
Calendar:
calendar_auth.py - Calendar authentication utilities
list_calendars.py - List accessible calendars
search_events.py - Search events by text/date
find_busy.py - Check free/busy periods
create_event.py - Create calendar events
Common Workflows
Schedule a Meeting
- Search calendar for availability:
search_events.py --start ... --end ...
- Create event:
create_event.py --summary "..." --start ... --end ...
Reply to Important Emails
- Find emails needing reply:
needs_reply.py
- Read specific email:
read_email.py <id>
- Create draft response:
create_draft.py --to ... --subject "Re: ..."