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

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

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