Google Workspace Integration

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

token.json

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

--description

--location

--timezone

--calendar

Scripts Reference

• 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_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: ..."