google-calendar

name	google-calendar
description	Manage your Google Calendar — view events, create meetings, check availability, and get reminders.

Google Calendar

Manage your Google Calendar — view events, create meetings, check availability, and get reminders.

Category: productivity API Key Required: Yes (Google OAuth or Service Account)

What It Does

Full Google Calendar integration: list upcoming events, create/edit/delete events, check free/busy slots, and search across calendars. Your agent becomes your scheduling assistant.

Setup

Option A: Using gcalcli (recommended, simplest)

# Install
pip3 install gcalcli

# Authenticate (opens browser for Google OAuth)
gcalcli list

This stores OAuth tokens locally. One-time setup.

Option B: Direct API with service account

1. Go to https://console.cloud.google.com
2. Enable the Google Calendar API
3. Create a service account, download the JSON key
4. Share your calendar with the service account email

Agent Commands (using gcalcli)

List upcoming events

gcalcli agenda --nocolor 2>/dev/null | head -30

Today's events

gcalcli agenda "today" "tomorrow" --nocolor 2>/dev/null

This week

gcalcli agenda "today" "+7d" --nocolor 2>/dev/null

Search events

gcalcli search "meeting" --nocolor 2>/dev/null | head -20

Create an event

gcalcli add --title "Team Standup" \
  --when "tomorrow 10:00" \
  --duration 30 \
  --description "Weekly sync" \
  --where "Zoom" \
  --noprompt

Create an all-day event

gcalcli add --title "Holiday" \
  --when "2026-03-15" \
  --allday \
  --noprompt

Quick add (natural language)

gcalcli quick "Lunch with Ollie tomorrow at 1pm"

Delete an event

gcalcli delete "Team Standup" --noprompt

List calendars

gcalcli list --nocolor 2>/dev/null

Agent Commands (using REST API)

If using a service account or OAuth token directly:

List upcoming events

curl -s -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  "https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10&orderBy=startTime&singleEvents=true&timeMin=$(date -u +%Y-%m-%dT%H:%M:%SZ)" | python3 -c "
import json,sys
d = json.load(sys.stdin)
for e in d.get('items',[]):
    start = e.get('start',{}).get('dateTime',e.get('start',{}).get('date',''))
    print(f\"{start:25s} {e.get('summary','No title')}\")
"

Create an event

curl -s -X POST -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  -d '{
    "summary": "Team Meeting",
    "description": "Weekly sync",
    "start": {"dateTime": "2026-02-21T10:00:00Z"},
    "end": {"dateTime": "2026-02-21T11:00:00Z"},
    "reminders": {"useDefault": true}
  }'

Check free/busy

curl -s -X POST -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://www.googleapis.com/calendar/v3/freeBusy" \
  -d '{
    "timeMin": "2026-02-21T00:00:00Z",
    "timeMax": "2026-02-21T23:59:59Z",
    "items": [{"id": "primary"}]
  }'

Examples

User: "What's on my calendar today?" → Run gcalcli agenda "today" "tomorrow", format nicely

User: "Schedule a call with the team tomorrow at 3pm" → gcalcli add --title "Team Call" --when "tomorrow 15:00" --duration 60 --noprompt

User: "Am I free Friday afternoon?" → Check agenda for Friday 12:00-18:00, report gaps

User: "Cancel the dentist appointment" → Search for "dentist", confirm with user, delete

Constraints

• gcalcli requires one-time OAuth setup (opens browser)
• Service accounts need calendar sharing setup
• Google API rate limit: 500 requests per 100 seconds per user
• All-day events use date format, timed events use dateTime
• Recurring events may need special handling