google-calendar

Google Calendar Integration

This skill provides access to Google Calendar via the Google Calendar API.

Setup Required

Uses OAuth with persistent refresh token (same setup for Calendar, Gmail, Drive).

One-time setup:

google-oauth-setup <path-to-client-secret.json>

See claude/skills/SETUP.md for detailed OAuth setup instructions.

Get Access Token (auto-refreshes):

ACCESS_TOKEN=$(google-oauth-token)

Required header for all requests:

-H "x-goog-user-project: ${GOOGLE_QUOTA_PROJECT}"

When to Use

Use this skill when the user:

• Asks about their calendar or schedule
• Wants to see today's or upcoming meetings
• Asks "what's on my calendar?"
• Needs to check availability
• Mentions meetings or events

API Endpoints

Base URL: https://www.googleapis.com/calendar/v3

List Calendars

curl -s "https://www.googleapis.com/calendar/v3/users/me/calendarList" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, id}'

Get Events

Today's Events:

TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -v+1d -u +"%Y-%m-%dT00:00:00Z")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${TODAY}" \
  --data-urlencode "timeMax=${TOMORROW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Next 7 Days:

NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
WEEK=$(date -v+7d -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "timeMax=${WEEK}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=20" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Specific Date Range:

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=2024-01-15T00:00:00Z" \
  --data-urlencode "timeMax=2024-01-22T00:00:00Z" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Search Events

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "q=standup" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Get Single Event

curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events/{EVENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Free/Busy Query

curl -s -X POST "https://www.googleapis.com/calendar/v3/freeBusy" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "2024-01-15T00:00:00Z",
    "timeMax": "2024-01-16T00:00:00Z",
    "items": [{"id": "primary"}]
  }'

Common Workflows

What's on my calendar today?

ACCESS_TOKEN=$(google-oauth-token)

TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -v+1d -u +"%Y-%m-%dT00:00:00Z")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${TODAY}" \
  --data-urlencode "timeMax=${TOMORROW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {
    summary,
    start: (.start.dateTime // .start.date),
    end: (.end.dateTime // .end.date),
    location
  }'

What meetings do I have this week?

NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
WEEK=$(date -v+7d -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "timeMax=${WEEK}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {
    summary,
    start: (.start.dateTime // .start.date),
    attendees: [.attendees[]?.email] | join(", ")
  }'

When is my next meeting?

NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[0] | {summary, start: .start.dateTime}'

Find a specific meeting

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "q=1:1" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=5" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, start: .start.dateTime}'

Event Properties

Key fields in event responses:

• summary: Event title
• start.dateTime / start.date: Start time (dateTime for timed events, date for all-day)
• end.dateTime / end.date: End time
• location: Meeting location or video link
• description: Event description
• attendees: Array of attendee objects with email, responseStatus
• hangoutLink: Google Meet link if present
• htmlLink: Link to view event in Google Calendar

Parameters

Notes

• Times must be in RFC3339 format (e.g., 2024-01-15T09:00:00Z or with timezone offset)
• Use singleEvents=true to expand recurring events
• primary refers to the user's primary calendar; use calendar ID for others
• Access tokens expire after 1 hour; refresh as needed
• All-day events use start.date instead of start.dateTime