Google Workspace Integration

Gmail and Google Calendar access via shared OAuth 2.0 authentication.

Prerequisites

1. Python 3.10+ available
2. Google Cloud project with Gmail API and Calendar API enabled
3. OAuth 2.0 credentials (credentials.json) downloaded
4. Required packages: google-api-python-client, google-auth-httplib2, google-auth-oauthlib

OAuth Setup

Step 1: Create Google Cloud Project

1. Go to https://console.cloud.google.com/
2. Create a new project or select existing
3. Navigate to APIs & Services → Library
4. Enable both Gmail API and Google Calendar API

Step 2: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External user type
3. 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
4. Add user’s email as a test user

Step 3: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Desktop app as application type
4. 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

# Search by text
uv run python tools/google-workspace/scripts/search_events.py "meeting" --credentials ./credentials.json

# Search by date range
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

1. Search calendar for availability: search_events.py --start ... --end ...
2. Create event: create_event.py --summary "..." --start ... --end ...

Reply to Important Emails

1. Find emails needing reply: needs_reply.py
2. Read specific email: read_email.py <id>
3. Create draft response: create_draft.py --to ... --subject "Re: ..."