Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download sanjay3290-ai-skills-skills_google-calendar-c842558.zip · 11 KB

Install

skills CLI npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/google-calendar
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
Git 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 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.

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.

No comments yet.

Reviews (0)

No reviews yet.