name	google-calendar-sync
description	Manages Google Calendar through the Calendar API. Create, read, update, and delete events, manage multiple calendars, set reminders, handle recurring events, and sync with local schedules. Use when working with Google Calendar, scheduling events, checking availability, managing meetings, or automating calendar workflows.

Google Calendar Sync

Comprehensive Google Calendar integration enabling event management, calendar organization, availability checking, recurring event handling, and workflow automation through the Google Calendar API v3.

Quick Start

When asked to work with Google Calendar:

Authenticate: Set up OAuth2 credentials (one-time setup)
List events: View upcoming events and meetings
Create events: Schedule new meetings and appointments
Update events: Modify existing events
Check availability: Find free time slots
Manage calendars: Work with multiple calendars

Prerequisites

One-Time Setup

1. Enable Calendar API:

# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Calendar API for your project
# APIs & Services > Enable APIs and Services > Google Calendar API

2. Create OAuth2 Credentials:

# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json

3. Install Dependencies:

pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client python-dateutil pytz --break-system-packages

4. Initial Authentication:

python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use

See reference/setup-guide.md for detailed setup.

Core Operations

List Events

View upcoming events:

# Today's events
python scripts/list_events.py --today

# This week
python scripts/list_events.py --days 7

# Specific date range
python scripts/list_events.py \
  --start 2025-01-01 \
  --end 2025-01-31

# Next N events
python scripts/list_events.py --limit 10

Filter events:

# By search term
python scripts/list_events.py --query "team meeting"

# By calendar
python scripts/list_events.py --calendar "Work"

# Only free/busy
python scripts/list_events.py --show-deleted false

Get event details:

# Get specific event
python scripts/get_event.py --event-id EVENT_ID

# Export to file
python scripts/get_event.py --event-id EVENT_ID --output event.json

Create Events

Simple event:

# Basic event
python scripts/create_event.py \
  --summary "Team Meeting" \
  --start "2025-01-20 14:00" \
  --end "2025-01-20 15:00"

# With description
python scripts/create_event.py \
  --summary "Project Review" \
  --start "2025-01-21 10:00" \
  --end "2025-01-21 11:00" \
  --description "Q4 project review meeting"

# With location
python scripts/create_event.py \
  --summary "Client Meeting" \
  --start "2025-01-22 14:00" \
  --end "2025-01-22 15:00" \
  --location "Conference Room A"

All-day event:

python scripts/create_event.py \
  --summary "Conference" \
  --start "2025-02-15" \
  --end "2025-02-17" \
  --all-day

With attendees:

python scripts/create_event.py \
  --summary "Team Standup" \
  --start "2025-01-20 09:00" \
  --duration 30 \
  --attendees "alice@company.com,bob@company.com" \
  --send-notifications

With reminders:

python scripts/create_event.py \
  --summary "Important Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --reminders "popup:10,email:60"  # 10 min popup, 60 min email

Video conference:

# Add Google Meet link
python scripts/create_event.py \
  --summary "Virtual Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --add-meet-link

Recurring Events

Create recurring:

# Daily standup
python scripts/create_recurring.py \
  --summary "Daily Standup" \
  --start "2025-01-20 09:00" \
  --duration 15 \
  --rule "FREQ=DAILY;COUNT=30"

# Weekly meeting
python scripts/create_recurring.py \
  --summary "Team Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --rule "FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20251231"

# Monthly review
python scripts/create_recurring.py \
  --summary "Monthly Review" \
  --start "2025-01-15 10:00" \
  --duration 120 \
  --rule "FREQ=MONTHLY;BYMONTHDAY=15"

Recurrence rule examples:

# Every weekday
"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"

# Every Monday and Wednesday
"FREQ=WEEKLY;BYDAY=MO,WE"

# First Monday of every month
"FREQ=MONTHLY;BYDAY=1MO"

# Every 2 weeks
"FREQ=WEEKLY;INTERVAL=2"

# Until specific date
"FREQ=DAILY;UNTIL=20251231T235959Z"

# Specific number of occurrences
"FREQ=WEEKLY;COUNT=10"

See reference/recurrence-rules.md for complete RRULE syntax.

Update Events

Modify event:

# Update time
python scripts/update_event.py \
  --event-id EVENT_ID \
  --start "2025-01-20 15:00" \
  --end "2025-01-20 16:00"

# Update summary and description
python scripts/update_event.py \
  --event-id EVENT_ID \
  --summary "Updated Meeting Title" \
  --description "New description"

# Add attendees
python scripts/update_event.py \
  --event-id EVENT_ID \
  --add-attendees "new@company.com"

# Move to different calendar
python scripts/move_event.py \
  --event-id EVENT_ID \
  --destination-calendar "Personal"

Update recurring instance:

# Update single instance
python scripts/update_event.py \
  --event-id EVENT_ID \
  --instance-date "2025-01-20" \
  --start "2025-01-20 16:00"

# Update all future instances
python scripts/update_event.py \
  --event-id EVENT_ID \
  --start "2025-01-20 16:00" \
  --update-following

Delete Events

Delete event:

# Delete single event
python scripts/delete_event.py --event-id EVENT_ID

# Delete recurring instance
python scripts/delete_event.py \
  --event-id EVENT_ID \
  --instance-date "2025-01-20"

# Delete all future instances
python scripts/delete_event.py \
  --event-id EVENT_ID \
  --delete-following

Check Availability

Find free time:

# Check availability
python scripts/check_availability.py \
  --start "2025-01-20 09:00" \
  --end "2025-01-20 17:00" \
  --duration 60

# Check multiple calendars
python scripts/check_availability.py \
  --calendars "Work,Personal" \
  --date "2025-01-20" \
  --duration 30

# Find next available slot
python scripts/find_next_slot.py \
  --duration 60 \
  --business-hours-only

FreeBusy query:

# Check if people are free
python scripts/check_freebusy.py \
  --emails "alice@company.com,bob@company.com" \
  --start "2025-01-20 14:00" \
  --end "2025-01-20 15:00"

Calendar Management

List calendars:

# Get all calendars
python scripts/list_calendars.py

# Get calendar details
python scripts/get_calendar.py --calendar-id "primary"

Create calendar:

# Create new calendar
python scripts/create_calendar.py \
  --summary "Project Alpha" \
  --description "Project Alpha team calendar" \
  --timezone "America/New_York"

Share calendar:

# Share with user
python scripts/share_calendar.py \
  --calendar-id CALENDAR_ID \
  --email "user@company.com" \
  --role writer

# Make public
python scripts/share_calendar.py \
  --calendar-id CALENDAR_ID \
  --public \
  --role reader

Calendar roles:

owner - Full control
writer - Create/modify events
reader - View only
freeBusyReader - See free/busy only

Common Workflows

Workflow 1: Schedule Meeting with Attendees

Scenario: Find time and schedule meeting

# 1. Check availability
python scripts/check_freebusy.py \
  --emails "alice@company.com,bob@company.com" \
  --date "2025-01-20" \
  --duration 60

# 2. Create meeting
python scripts/create_event.py \
  --summary "Project Discussion" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --attendees "alice@company.com,bob@company.com" \
  --add-meet-link \
  --send-notifications

Workflow 2: Sync with Local Calendar

Scenario: Export/import events

# Export to ICS
python scripts/export_calendar.py \
  --calendar-id "primary" \
  --output calendar.ics \
  --start "2025-01-01" \
  --end "2025-12-31"

# Import from ICS
python scripts/import_calendar.py \
  --file events.ics \
  --calendar-id "primary"

Workflow 3: Daily Schedule Summary

Scenario: Get morning email with day's schedule

# Generate daily summary
python scripts/daily_summary.py \
  --send-email \
  --to "me@company.com"

Workflow 4: Recurring Task Events

Scenario: Create recurring reminders

# Create recurring task
python scripts/create_recurring.py \
  --summary "Submit Weekly Report" \
  --start "2025-01-20 16:00" \
  --duration 30 \
  --rule "FREQ=WEEKLY;BYDAY=FR" \
  --reminders "popup:0"

Workflow 5: Event Analytics

Scenario: Analyze calendar usage

# Generate statistics
python scripts/calendar_stats.py \
  --start "2025-01-01" \
  --end "2025-01-31" \
  --output stats.json

# Meeting time analysis
python scripts/meeting_analysis.py --days 30

Event Colors

Color IDs:

COLORS = {
    '1': 'Lavender',
    '2': 'Sage',
    '3': 'Grape',
    '4': 'Flamingo',
    '5': 'Banana',
    '6': 'Tangerine',
    '7': 'Peacock',
    '8': 'Graphite',
    '9': 'Blueberry',
    '10': 'Basil',
    '11': 'Tomato'
}

Set event color:

python scripts/update_event.py \
  --event-id EVENT_ID \
  --color-id 9  # Blueberry

Reminder Options

Reminder methods:

popup - In-app notification
email - Email reminder

Reminder timing:

# Minutes before event
reminders = [
    {'method': 'popup', 'minutes': 10},
    {'method': 'email', 'minutes': 60},
    {'method': 'popup', 'minutes': 1440}  # 1 day
]

Use default reminders:

# Use calendar's default reminders
'useDefault': True

Time Zones

Specify timezone:

# Event in specific timezone
python scripts/create_event.py \
  --summary "Meeting" \
  --start "2025-01-20 14:00" \
  --timezone "America/Los_Angeles" \
  --duration 60

Common timezones:

'America/New_York'
'America/Chicago'
'America/Denver'
'America/Los_Angeles'
'Europe/London'
'Europe/Paris'
'Asia/Tokyo'
'Australia/Sydney'
'UTC'

Event Status

Status values:

confirmed - Event is confirmed (default)
tentative - Event is tentative
cancelled - Event is cancelled

Set status:

python scripts/update_event.py \
  --event-id EVENT_ID \
  --status tentative

Visibility Settings

Visibility options:

default - Default visibility
public - Public event
private - Private event
confidential - Only time shown, details hidden

Set visibility:

python scripts/update_event.py \
  --event-id EVENT_ID \
  --visibility private

API Rate Limits

Calendar API quotas:

Queries per day: 1,000,000
Queries per 100 seconds per user: 500

Best practices:

Batch operations when possible
Cache calendar data
Use incremental sync for updates
Implement exponential backoff

OAuth Scopes

# Full access
'https://www.googleapis.com/auth/calendar'

# Read-only
'https://www.googleapis.com/auth/calendar.readonly'

# Events only
'https://www.googleapis.com/auth/calendar.events'

# Events read-only
'https://www.googleapis.com/auth/calendar.events.readonly'

# Settings only
'https://www.googleapis.com/auth/calendar.settings.readonly'

Scripts Reference

Authentication:

authenticate.py - OAuth setup
refresh_token.py - Refresh token

Events:

list_events.py - List events
get_event.py - Get event details
create_event.py - Create event
create_recurring.py - Create recurring event
update_event.py - Update event
delete_event.py - Delete event
move_event.py - Move to different calendar

Availability:

check_availability.py - Check free time
find_next_slot.py - Find next available
check_freebusy.py - FreeBusy query

Calendars:

list_calendars.py - List all calendars
get_calendar.py - Get calendar details
create_calendar.py - Create calendar
share_calendar.py - Share calendar

Import/Export:

export_calendar.py - Export to ICS
import_calendar.py - Import from ICS

Automation:

daily_summary.py - Daily schedule email
weekly_report.py - Weekly calendar report
sync_calendar.py - Sync with external source

Analytics:

calendar_stats.py - Usage statistics
meeting_analysis.py - Meeting patterns
time_tracking.py - Track time allocation

Best Practices

Use RFC3339 format: For dates/times (2025-01-20T14:00:00-08:00)
Specify timezones: Avoid ambiguity
Send notifications: When adding/updating attendees
Use batch requests: For multiple operations
Handle recurring events carefully: Understand instance vs series
Cache calendar lists: Reduce API calls
Implement sync tokens: For incremental updates
Respect quotas: Monitor usage

Integration Examples

See examples/ for complete workflows:

examples/meeting-scheduler.md - Automated meeting scheduling
examples/calendar-sync.md - Multi-calendar synchronization
examples/reminder-system.md - Custom reminder workflows
examples/analytics.md - Calendar analytics and insights

Troubleshooting

"Invalid time zone"

Use IANA timezone names
Check spelling
Reference: https://www.iana.org/time-zones

"Invalid recurrence rule"

Verify RRULE syntax
Use FREQ, COUNT/UNTIL, and optional parameters
See reference/recurrence-rules.md

"Event not found"

Event may be deleted
Check calendar ID
Verify event ID

"Insufficient permissions"

Check OAuth scopes
Re-authenticate with needed scopes

Reference Documentation

reference/setup-guide.md - Setup instructions
reference/recurrence-rules.md - RRULE reference
reference/api-reference.md - API documentation
reference/timezone-reference.md - Timezone list

google-calendar-sync

Install Skill

SKILL.md