google-calendar
Google Calendar API — list events, create/update/delete appointments, check availability. Direct OAuth via service account, no third-party proxy.
SKILL.mdskills/google-calendar/SKILL.md
GitHubGoogle Calendar
Manage Google Calendar events directly via Google Calendar API. All scripts output JSON.
Setup
1. Create a Google Cloud project
- Go to Google Cloud Console
- Create a new project (or select an existing one)
- Enable the Google Calendar API:
- Go to APIs & Services > Library
- Search "Google Calendar API" and click Enable
2. Create a service account
- Go to APIs & Services > Credentials
- Click Create Credentials > Service account
- Name it (e.g.
nyxclaw-calendar) and click Create - Skip the optional permissions steps, click Done
- Click on the created service account
- Go to Keys > Add Key > Create new key > JSON
- Download the JSON file — this is your credential
3. Share your calendar with the service account
- Open Google Calendar
- Click the three dots next to your calendar > Settings and sharing
- Under Share with specific people, click Add people
- Paste the service account email (from the JSON file, field
client_email— looks likename@project.iam.gserviceaccount.com) - Set permission to Make changes to events
- Click Send
4. Configure in NyxClaw
Tell Nyx:
"set env GOOGLE_SERVICE_ACCOUNT_JSON to (paste the entire JSON content)" "set env GOOGLE_CALENDAR_ID to (your calendar ID from step 3)"
The GOOGLE_CALENDAR_ID is the default calendar for all operations. Find it in Google Calendar > Settings > Integrate calendar. Format: abc123...@group.calendar.google.com (for custom calendars) or your email (for personal calendar).
If you already use GOOGLE_SERVICE_ACCOUNT_JSON for GSC Analytics, the same service account works — just share the calendar with it.
5. (Optional) Domain-wide delegation
For Google Workspace accounts, you can impersonate users:
- Go to Admin console > Security > API Controls > Domain-wide delegation
- Add the service account client ID with scope
https://www.googleapis.com/auth/calendar - Set
GOOGLE_CALENDAR_USERenv var to the email to impersonate
List Events
node {baseDir}/scripts/events.mjs list
node {baseDir}/scripts/events.mjs list --days 14 --limit 50
node {baseDir}/scripts/events.mjs list --calendar "other@gmail.com" --days 30
Options:
--days <n>: Look-ahead window in days (default: 7)--limit <n>: Max events to return (default: 25)--calendar <id>: Calendar ID — must be the full ID, not the display name (default: primary, which is the service account's own calendar). Usecalendars.mjsto discover IDs
Get Event
node {baseDir}/scripts/events.mjs get <eventId>
Create Event
node {baseDir}/scripts/events.mjs create "Dental Appointment" "2026-03-10T09:00:00" "2026-03-10T10:00:00"
node {baseDir}/scripts/events.mjs create "Team Sync" "2026-03-10T15:00:00" "2026-03-10T16:00:00" --description "Weekly sync" --attendees "john@example.com,jane@example.com"
node {baseDir}/scripts/events.mjs create "Holiday" "2026-03-15" "2026-03-16"
Options:
--timezone <tz>: Timezone (default: Europe/Madrid)--description <text>: Event description--attendees <emails>: Comma-separated list of attendee emails
Quick Add (natural language)
node {baseDir}/scripts/events.mjs quickadd "Meeting with John tomorrow at 3pm"
Update Event
node {baseDir}/scripts/events.mjs update <eventId> '{"summary":"New Title"}'
node {baseDir}/scripts/events.mjs update <eventId> '{"start":{"dateTime":"2026-03-10T10:00:00","timeZone":"Europe/Madrid"}}'
Delete Event
node {baseDir}/scripts/events.mjs delete <eventId>
List Calendars
node {baseDir}/scripts/calendars.mjs
Check Availability (Free/Busy)
node {baseDir}/scripts/freebusy.mjs
node {baseDir}/scripts/freebusy.mjs --days 14
node {baseDir}/scripts/freebusy.mjs --calendar "other@gmail.com"
Notes
- Environment variables are auto-injected —
GOOGLE_SERVICE_ACCOUNT_JSON,GOOGLE_CALENDAR_IDand allenv.varsfrom nyxclaw.json are available asprocess.env.*when scripts run. Do NOT verify them manually via CLI — just run the scripts directly. - The default calendar is
GOOGLE_CALENDAR_IDenv var. Override per-command with--calendar <id>. - The service account must be shared on the target calendar with "Make changes to events" permission.
- All scripts authenticate automatically via
auth.mjs. - Times in RFC3339 format (e.g.
2026-03-10T09:00:00) or date-only for all-day events (2026-03-10). - If you already have
GOOGLE_SERVICE_ACCOUNT_JSONconfigured for gsc-analytics, the same key works — just share the calendar. - Calendar ID vs display name: The
--calendarflag requires the full calendar ID (e.g.abc123...@group.calendar.google.com), not the display name. Runcalendars.mjsfirst to discover IDs.