google-calendar
Interact with Google Calendar - list calendars, view events, create/update/delete events, and find free time. Use when user asks to: check calendar, schedule a meeting, create an event, find available time, list upcoming events, delete or update a calendar event, or respond to me
Install
npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/google-calendar
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
git clone https://github.com/sanjay3290/ai-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sanjay3290/ai-skills collection as a plugin from our marketplace. Git is the plain clone.
README
Google Calendar Skill
An AI agent skill for interacting with Google Calendar - list events, create/update/delete events, find free time, and respond to invitations. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the Agent Skills Standard.
Features
- List Events - View upcoming events with time range filtering
- Create Events - Schedule meetings with attendees
- Update Events - Modify existing events
- Delete Events - Remove calendar entries
- Find Free Time - Discover available slots across attendees
- Respond to Invitations - Accept, decline, or mark tentative
Lightweight alternative to the full Google Workspace MCP server.
⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.
Quick Start
1. Install dependencies
pip install keyring
2. Authenticate
python scripts/auth.py login
This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.
3. Test connection
python scripts/auth.py status
Usage Examples
List Events
# List events from primary calendar (default: next 30 days)
python scripts/gcal.py list-events
# List events with time range
python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z
# List from specific calendar
python scripts/gcal.py list-events --calendar "work@example.com"
Create Events
# Basic event
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z"
# With description and location
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
--description "Weekly sync" --location "Conference Room A"
# With attendees
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
--attendees user1@example.com user2@example.com
Update Events
python scripts/gcal.py update-event EVENT_ID --summary "New Title"
python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z"
Find Free Time
# Find 30-minute slot for yourself
python scripts/gcal.py find-free-time \
--attendees me \
--time-min "2024-01-15T09:00:00Z" \
--time-max "2024-01-15T17:00:00Z" \
--duration 30
# Find 60-minute slot with multiple attendees
python scripts/gcal.py find-free-time \
--attendees me user1@example.com user2@example.com \
--time-min "2024-01-15T09:00:00Z" \
--time-max "2024-01-19T17:00:00Z" \
--duration 60
Respond to Invitations
python scripts/gcal.py respond-to-event EVENT_ID accepted
python scripts/gcal.py respond-to-event EVENT_ID declined
python scripts/gcal.py respond-to-event EVENT_ID tentative
Command Reference
| Command | Description | Arguments |
|---|---|---|
list-calendars |
List all calendars | - |
list-events |
List events | --calendar, --time-min, --time-max |
get-event <id> |
Get event details | event ID |
create-event <title> <start> <end> |
Create event | title, times, --attendees |
update-event <id> |
Update event | event ID, fields to update |
delete-event <id> |
Delete event | event ID |
find-free-time |
Find available slots | --attendees, --duration |
respond-to-event <id> <response> |
Respond to invite | event ID, accepted/declined/tentative |
Date/Time Format
All times use ISO 8601 format:
- UTC:
2024-01-15T10:30:00Z - With offset:
2024-01-15T10:30:00-05:00 - Local time (offset added automatically):
2024-01-15T10:30:00
Token Management
Tokens stored securely using the system keyring:
- macOS: Keychain
- Windows: Windows Credential Locker
- Linux: Secret Service API (GNOME Keyring, KDE Wallet)
Service name: google-calendar-skill-oauth
Troubleshooting
"Failed to get access token"
Run python scripts/auth.py login to authenticate.
"Event not found"
Check the event ID and your calendar access.
"No free time found"
Try a wider time range or longer duration.
License
Apache 2.0
Skill manifest
Google Calendar
Lightweight Google Calendar integration with standalone OAuth authentication. No MCP server required.
⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.
First-Time Setup
Authenticate with Google (opens browser):
python scripts/auth.py login
Check authentication status:
python scripts/auth.py status
Logout when needed:
python scripts/auth.py logout
Commands
All operations via scripts/gcal.py. Auto-authenticates on first use if not logged in.
List Calendars
python scripts/gcal.py list-calendars
List Events
# List events from primary calendar (default: next 30 days)
python scripts/gcal.py list-events
# List events with specific time range
python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z
# List events from a specific calendar
python scripts/gcal.py list-events --calendar "work@example.com"
# Limit results
python scripts/gcal.py list-events --max-results 10
Get Event Details
python scripts/gcal.py get-event EVENT_ID
python scripts/gcal.py get-event EVENT_ID --calendar "work@example.com"
Create Event
# Basic event
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z"
# Event with description and location
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
--description "Weekly sync" --location "Conference Room A"
# Event with attendees
python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
--attendees user1@example.com user2@example.com
# Event on specific calendar
python scripts/gcal.py create-event "Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \
--calendar "work@example.com"
Update Event
# Update event title
python scripts/gcal.py update-event EVENT_ID --summary "New Title"
# Update event time
python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z"
# Update multiple fields
python scripts/gcal.py update-event EVENT_ID \
--summary "Updated Meeting" --description "New agenda" --location "Room B"
# Update attendees
python scripts/gcal.py update-event EVENT_ID --attendees user1@example.com user3@example.com
Delete Event
python scripts/gcal.py delete-event EVENT_ID
python scripts/gcal.py delete-event EVENT_ID --calendar "work@example.com"
Find Free Time
Find the first available slot for a meeting with specified attendees:
# Find 30-minute slot for yourself
python scripts/gcal.py find-free-time \
--attendees me \
--time-min "2024-01-15T09:00:00Z" \
--time-max "2024-01-15T17:00:00Z" \
--duration 30
# Find 60-minute slot with multiple attendees
python scripts/gcal.py find-free-time \
--attendees me user1@example.com user2@example.com \
--time-min "2024-01-15T09:00:00Z" \
--time-max "2024-01-19T17:00:00Z" \
--duration 60
Respond to Event Invitation
# Accept an invitation
python scripts/gcal.py respond-to-event EVENT_ID accepted
# Decline an invitation
python scripts/gcal.py respond-to-event EVENT_ID declined
# Mark as tentative
python scripts/gcal.py respond-to-event EVENT_ID tentative
# Respond without notifying organizer
python scripts/gcal.py respond-to-event EVENT_ID accepted --no-notify
Date/Time Format
All times use ISO 8601 format with timezone:
- UTC:
2024-01-15T10:30:00Z - With offset:
2024-01-15T10:30:00-05:00(EST)
Calendar ID Format
- Primary calendar: Use
primaryor omit the--calendarflag - Other calendars: Use the calendar ID from
list-calendars(usually an email address)
Token Management
Tokens stored securely using the system keyring:
- macOS: Keychain
- Windows: Windows Credential Locker
- Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)
Service name: google-calendar-skill-oauth
Tokens are automatically refreshed when expired using Google's cloud function.
Files (ai-skills)
-
scripts
-
auth.py 13.1 KB
Loading… -
gcal.py 17.6 KB
Loading… -
requirements.txt 16 B
Loading…
-
-
README.md 4.2 KB
# Google Calendar Skill An AI agent skill for interacting with Google Calendar - list events, create/update/delete events, find free time, and respond to invitations. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the [Agent Skills Standard](https://agentskills.io). ## Features - **List Events** - View upcoming events with time range filtering - **Create Events** - Schedule meetings with attendees - **Update Events** - Modify existing events - **Delete Events** - Remove calendar entries - **Find Free Time** - Discover available slots across attendees - **Respond to Invitations** - Accept, decline, or mark tentative Lightweight alternative to the full [Google Workspace MCP server](https://github.com/gemini-cli-extensions/workspace). > **⚠️ Requires Google Workspace account.** Personal Gmail accounts are not supported. ## Quick Start ### 1. Install dependencies ```bash pip install keyring ``` ### 2. Authenticate ```bash python scripts/auth.py login ``` This opens a browser for Google OAuth. Tokens are stored securely in your system keyring. ### 3. Test connection ```bash python scripts/auth.py status ``` ## Usage Examples ### List Events ```bash # List events from primary calendar (default: next 30 days) python scripts/gcal.py list-events # List events with time range python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z # List from specific calendar python scripts/gcal.py list-events --calendar "work@example.com" ``` ### Create Events ```bash # Basic event python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" # With description and location python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \ --description "Weekly sync" --location "Conference Room A" # With attendees python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \ --attendees user1@example.com user2@example.com ``` ### Update Events ```bash python scripts/gcal.py update-event EVENT_ID --summary "New Title" python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z" ``` ### Find Free Time ```bash # Find 30-minute slot for yourself python scripts/gcal.py find-free-time \ --attendees me \ --time-min "2024-01-15T09:00:00Z" \ --time-max "2024-01-15T17:00:00Z" \ --duration 30 # Find 60-minute slot with multiple attendees python scripts/gcal.py find-free-time \ --attendees me user1@example.com user2@example.com \ --time-min "2024-01-15T09:00:00Z" \ --time-max "2024-01-19T17:00:00Z" \ --duration 60 ``` ### Respond to Invitations ```bash python scripts/gcal.py respond-to-event EVENT_ID accepted python scripts/gcal.py respond-to-event EVENT_ID declined python scripts/gcal.py respond-to-event EVENT_ID tentative ``` ## Command Reference | Command | Description | Arguments | |---------|-------------|-----------| | `list-calendars` | List all calendars | - | | `list-events` | List events | `--calendar`, `--time-min`, `--time-max` | | `get-event <id>` | Get event details | event ID | | `create-event <title> <start> <end>` | Create event | title, times, `--attendees` | | `update-event <id>` | Update event | event ID, fields to update | | `delete-event <id>` | Delete event | event ID | | `find-free-time` | Find available slots | `--attendees`, `--duration` | | `respond-to-event <id> <response>` | Respond to invite | event ID, accepted/declined/tentative | ## Date/Time Format All times use ISO 8601 format: - UTC: `2024-01-15T10:30:00Z` - With offset: `2024-01-15T10:30:00-05:00` - Local time (offset added automatically): `2024-01-15T10:30:00` ## Token Management Tokens stored securely using the system keyring: - **macOS**: Keychain - **Windows**: Windows Credential Locker - **Linux**: Secret Service API (GNOME Keyring, KDE Wallet) Service name: `google-calendar-skill-oauth` ## Troubleshooting ### "Failed to get access token" Run `python scripts/auth.py login` to authenticate. ### "Event not found" Check the event ID and your calendar access. ### "No free time found" Try a wider time range or longer duration. ## License Apache 2.0 -
requirements.txt 16 B
Loading… -
SKILL.md 4.5 KB
--- name: google-calendar description: | Interact with Google Calendar - list calendars, view events, create/update/delete events, and find free time. Use when user asks to: check calendar, schedule a meeting, create an event, find available time, list upcoming events, delete or update a calendar event, or respond to meeting invitations. Lightweight alternative to full Google Workspace MCP server with standalone OAuth authentication. license: Apache-2.0 metadata: author: sanjay3290 version: "1.0" --- # Google Calendar Lightweight Google Calendar integration with standalone OAuth authentication. No MCP server required. > **⚠️ Requires Google Workspace account.** Personal Gmail accounts are not supported. ## First-Time Setup Authenticate with Google (opens browser): ```bash python scripts/auth.py login ``` Check authentication status: ```bash python scripts/auth.py status ``` Logout when needed: ```bash python scripts/auth.py logout ``` ## Commands All operations via `scripts/gcal.py`. Auto-authenticates on first use if not logged in. ### List Calendars ```bash python scripts/gcal.py list-calendars ``` ### List Events ```bash # List events from primary calendar (default: next 30 days) python scripts/gcal.py list-events # List events with specific time range python scripts/gcal.py list-events --time-min 2024-01-15T00:00:00Z --time-max 2024-01-31T23:59:59Z # List events from a specific calendar python scripts/gcal.py list-events --calendar "work@example.com" # Limit results python scripts/gcal.py list-events --max-results 10 ``` ### Get Event Details ```bash python scripts/gcal.py get-event EVENT_ID python scripts/gcal.py get-event EVENT_ID --calendar "work@example.com" ``` ### Create Event ```bash # Basic event python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" # Event with description and location python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \ --description "Weekly sync" --location "Conference Room A" # Event with attendees python scripts/gcal.py create-event "Team Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \ --attendees user1@example.com user2@example.com # Event on specific calendar python scripts/gcal.py create-event "Meeting" "2024-01-15T10:00:00Z" "2024-01-15T11:00:00Z" \ --calendar "work@example.com" ``` ### Update Event ```bash # Update event title python scripts/gcal.py update-event EVENT_ID --summary "New Title" # Update event time python scripts/gcal.py update-event EVENT_ID --start "2024-01-15T14:00:00Z" --end "2024-01-15T15:00:00Z" # Update multiple fields python scripts/gcal.py update-event EVENT_ID \ --summary "Updated Meeting" --description "New agenda" --location "Room B" # Update attendees python scripts/gcal.py update-event EVENT_ID --attendees user1@example.com user3@example.com ``` ### Delete Event ```bash python scripts/gcal.py delete-event EVENT_ID python scripts/gcal.py delete-event EVENT_ID --calendar "work@example.com" ``` ### Find Free Time Find the first available slot for a meeting with specified attendees: ```bash # Find 30-minute slot for yourself python scripts/gcal.py find-free-time \ --attendees me \ --time-min "2024-01-15T09:00:00Z" \ --time-max "2024-01-15T17:00:00Z" \ --duration 30 # Find 60-minute slot with multiple attendees python scripts/gcal.py find-free-time \ --attendees me user1@example.com user2@example.com \ --time-min "2024-01-15T09:00:00Z" \ --time-max "2024-01-19T17:00:00Z" \ --duration 60 ``` ### Respond to Event Invitation ```bash # Accept an invitation python scripts/gcal.py respond-to-event EVENT_ID accepted # Decline an invitation python scripts/gcal.py respond-to-event EVENT_ID declined # Mark as tentative python scripts/gcal.py respond-to-event EVENT_ID tentative # Respond without notifying organizer python scripts/gcal.py respond-to-event EVENT_ID accepted --no-notify ``` ## Date/Time Format All times use ISO 8601 format with timezone: - UTC: `2024-01-15T10:30:00Z` - With offset: `2024-01-15T10:30:00-05:00` (EST) ## Calendar ID Format - Primary calendar: Use `primary` or omit the `--calendar` flag - Other calendars: Use the calendar ID from `list-calendars` (usually an email address) ## Token Management Tokens stored securely using the system keyring: - **macOS**: Keychain - **Windows**: Windows Credential Locker - **Linux**: Secret Service API (GNOME Keyring, KDE Wallet, etc.) Service name: `google-calendar-skill-oauth` Tokens are automatically refreshed when expired using Google's cloud function.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.