Google Workspace Integration¶

Google Workspace integration provides access to Gmail, Google Calendar, Google Drive, and Google Sheets.

Configuration¶

Service Account: aegis@richardbankole.com Credentials: ~/.secure/google-workspace-credentials.json

Configuration in ~/.claude.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/google-workspace/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/home/agent/.secure/google-workspace-credentials.json"
      }
    }
  }
}

Gmail¶

See Email Integration for detailed Gmail documentation.

Quick Reference¶

# Search emails
results = mcp__google_workspace__gmail_search(query="is:unread", max_results=50)

# Send email
mcp__google_workspace__gmail_send(to="user@example.com", subject="Title", body="Content")

# Mark as read
mcp__google_workspace__gmail_modify(message_id="abc123", remove_labels=["UNREAD"])

Google Calendar¶

Access and manage calendar events.

List Events¶

# Get events for today
from datetime import datetime, timedelta

today = datetime.now()
tomorrow = today + timedelta(days=1)

events = mcp__google_workspace__calendar_list_events(
    calendar_id="primary",
    time_min=today.isoformat(),
    time_max=tomorrow.isoformat(),
    max_results=50
)

Create Event¶

event = mcp__google_workspace__calendar_create_event(
    calendar_id="primary",
    summary="Team Meeting",
    description="Discuss Q1 roadmap",
    location="Conference Room A",
    start_time="2026-01-26T14:00:00",
    end_time="2026-01-26T15:00:00",
    attendees=["team@example.com"],
    timezone="UTC"
)

Update Event¶

mcp__google_workspace__calendar_update_event(
    calendar_id="primary",
    event_id="abc123",
    summary="Updated Meeting Title",
    start_time="2026-01-26T15:00:00",
    end_time="2026-01-26T16:00:00"
)

Delete Event¶

mcp__google_workspace__calendar_delete_event(
    calendar_id="primary",
    event_id="abc123"
)

Database Caching¶

Calendar events are cached in PostgreSQL:

CREATE TABLE calendar_cache (
    id SERIAL PRIMARY KEY,
    event_id TEXT UNIQUE NOT NULL,
    calendar_id TEXT,
    title TEXT,
    description TEXT,
    location TEXT,
    event_start TIMESTAMPTZ,
    event_end TIMESTAMPTZ,
    event_date DATE,
    attendees TEXT[],
    organizer TEXT,
    status TEXT,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

Daily Schedule¶

Part of morning/evening routines:

# Get today's schedule
today = datetime.now().date()
events = db.fetch_all("""
    SELECT title, event_start, event_end, location
    FROM calendar_cache
    WHERE event_date = %s
    ORDER BY event_start
""", (today,))

if events:
    for event in events:
        start = event['event_start'].strftime('%H:%M')
        title = event['title'][:40]
        print(f"{start} - {title}")

Google Drive¶

Access and manage files in Google Drive.

List Files¶

# List recent files
files = mcp__google_workspace__drive_list_files(
    max_results=20,
    order_by="modifiedTime desc"
)

# Search by name
files = mcp__google_workspace__drive_list_files(
    query="name contains 'report'",
    max_results=10
)

# Filter by MIME type
files = mcp__google_workspace__drive_list_files(
    query="mimeType='application/pdf'",
    max_results=50
)

Get File¶

# Get file metadata
file = mcp__google_workspace__drive_get_file(
    file_id="abc123"
)

# Download file content
content = mcp__google_workspace__drive_download_file(
    file_id="abc123"
)

Create File¶

file = mcp__google_workspace__drive_create_file(
    name="Report.pdf",
    mime_type="application/pdf",
    content=base64_encoded_content,
    folder_id="parent_folder_id"  # Optional
)

Update File¶

mcp__google_workspace__drive_update_file(
    file_id="abc123",
    name="Updated Report.pdf",
    content=base64_encoded_content
)

# Share with specific user
mcp__google_workspace__drive_share_file(
    file_id="abc123",
    email="user@example.com",
    role="reader"  # reader, writer, commenter
)

# Create shareable link
mcp__google_workspace__drive_create_permission(
    file_id="abc123",
    role="reader",
    type="anyone"  # Public link
)

Search Queries¶

# Files owned by me
query = "'me' in owners"

# Files shared with me
query = "sharedWithMe = true"

# Files in trash
query = "trashed = true"

# Modified after date
query = "modifiedTime > '2026-01-01T00:00:00'"

# Combine filters
query = "name contains 'report' and mimeType='application/pdf' and not trashed"

Google Sheets¶

Read and write spreadsheet data.

Read Spreadsheet¶

# Get values from range
data = mcp__google_workspace__sheets_get_values(
    spreadsheet_id="abc123",
    range="Sheet1!A1:D10"
)
# Returns: [["Name", "Email", "Status"], ["John", "john@example.com", "Active"], ...]

# Get multiple ranges
data = mcp__google_workspace__sheets_batch_get(
    spreadsheet_id="abc123",
    ranges=["Sheet1!A1:D10", "Sheet2!A1:B5"]
)

Write to Spreadsheet¶

# Update values
mcp__google_workspace__sheets_update_values(
    spreadsheet_id="abc123",
    range="Sheet1!A1:C2",
    values=[
        ["Name", "Email", "Status"],
        ["John Doe", "john@example.com", "Active"]
    ],
    value_input_option="USER_ENTERED"  # or "RAW"
)

# Append rows
mcp__google_workspace__sheets_append_values(
    spreadsheet_id="abc123",
    range="Sheet1!A:C",
    values=[
        ["Jane Doe", "jane@example.com", "Active"]
    ]
)

Create Spreadsheet¶

spreadsheet = mcp__google_workspace__sheets_create(
    title="New Report",
    sheets=[
        {"title": "Summary", "rowCount": 100, "columnCount": 10},
        {"title": "Details", "rowCount": 1000, "columnCount": 20}
    ]
)

Format Cells¶

# Bold header row
mcp__google_workspace__sheets_format_cells(
    spreadsheet_id="abc123",
    range="Sheet1!A1:Z1",
    format={
        "textFormat": {"bold": True},
        "backgroundColor": {"red": 0.9, "green": 0.9, "blue": 0.9}
    }
)

Authentication¶

Service Account Setup¶

Create service account in Google Cloud Console
Enable APIs:
Gmail API
Google Calendar API
Google Drive API
Google Sheets API
Create and download credentials JSON
Store in ~/.secure/google-workspace-credentials.json

Domain-Wide Delegation¶

For accessing user data: 1. Enable domain-wide delegation in service account settings 2. Add scopes in Google Workspace Admin Console 3. Authorize service account client ID

Required scopes:

https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/spreadsheets

Rate Limits¶

Gmail¶

10,000 quota units per day (free tier)
1 quota unit per read operation
5 quota units per send operation

Calendar¶

1,000,000 queries per day
10,000 requests per 100 seconds per user

Drive¶

20,000 queries per 100 seconds per user
12,000 queries per 100 seconds (global)

Sheets¶

100 requests per 100 seconds per user
500 requests per 100 seconds per project

Best Practices¶

Cache Locally: Store frequently accessed data in PostgreSQL
Batch Operations: Use batch APIs when updating multiple items
Exponential Backoff: Retry with backoff on rate limit errors
Selective Syncing: Only sync what you need
Monitor Quotas: Track usage in Google Cloud Console

Integration Examples¶

Morning Routine¶

# Sync calendar for today
today = datetime.now()
tomorrow = today + timedelta(days=1)

events = mcp__google_workspace__calendar_list_events(
    calendar_id="primary",
    time_min=today.isoformat(),
    time_max=tomorrow.isoformat()
)

# Cache in database
for event in events:
    db.execute("""
        INSERT INTO calendar_cache (event_id, title, event_start, event_end, event_date)
        VALUES (%s, %s, %s, %s, %s)
        ON CONFLICT (event_id) DO UPDATE SET
            title = EXCLUDED.title,
            event_start = EXCLUDED.event_start,
            event_end = EXCLUDED.event_end,
            updated_at = NOW()
    """, (event['id'], event['summary'], event['start'], event['end'], today))

# Report to WhatsApp
if events:
    summary = f"📆 Today: {len(events)} events\n"
    for e in events[:3]:
        summary += f"• {e['start'].strftime('%H:%M')} - {e['summary']}\n"

    send_whatsapp_message("447490195079", summary)

Email Triage with Drive Storage¶

# Triage emails
urgent_emails = triage_unread()

# Create report in Google Sheets
report = mcp__google_workspace__sheets_create(title=f"Email Triage {date}")

data = [["From", "Subject", "Category", "Priority"]]
for email in urgent_emails:
    data.append([email['from'], email['subject'], email['category'], email['priority']])

mcp__google_workspace__sheets_update_values(
    spreadsheet_id=report['id'],
    range="Sheet1!A1:D100",
    values=data
)

# Share with user
mcp__google_workspace__drive_share_file(
    file_id=report['id'],
    email="user@example.com",
    role="reader"
)

Troubleshooting¶

Credentials Not Found¶

# Verify credentials file exists
ls -la ~/.secure/google-workspace-credentials.json

# Check permissions
chmod 600 ~/.secure/google-workspace-credentials.json

API Not Enabled¶

Enable APIs in Google Cloud Console: https://console.cloud.google.com/apis/library

Permission Denied¶

Verify service account has domain-wide delegation and required scopes in Google Workspace Admin Console.

Quota Exceeded¶

Check quota usage: https://console.cloud.google.com/apis/dashboard

Implement exponential backoff:

import time

retries = 0
while retries < 5:
    try:
        result = mcp__google_workspace__gmail_search(...)
        break
    except QuotaExceededError:
        wait = 2 ** retries
        time.sleep(wait)
        retries += 1

Google Workspace Integration¶

Configuration¶

Gmail¶

Quick Reference¶

Google Calendar¶

List Events¶

Create Event¶

Update Event¶

Delete Event¶

Database Caching¶

Daily Schedule¶

Google Drive¶

List Files¶

Get File¶

Create File¶

Update File¶

Share File¶

Search Queries¶

Google Sheets¶

Read Spreadsheet¶

Write to Spreadsheet¶

Create Spreadsheet¶

Format Cells¶

Authentication¶

Service Account Setup¶

Domain-Wide Delegation¶

Rate Limits¶

Gmail¶

Calendar¶

Drive¶

Sheets¶

Best Practices¶

Integration Examples¶

Morning Routine¶

Email Triage with Drive Storage¶

Troubleshooting¶

Credentials Not Found¶

API Not Enabled¶

Permission Denied¶

Quota Exceeded¶