Google Calendar Server

Manage events and schedules in Google Calendar

Overview

The Google Calendar server enables AI agents to list, create, and update calendar events. It provides comprehensive calendar management capabilities.

Prerequisites

• Python 3.11+
• A Google Cloud Project with Google Calendar API enabled
• OAuth 2.0 credentials with scope: https://www.googleapis.com/auth/calendar

Authentication

Setup OAuth Credentials

1. Create a new Google Cloud project
2. Enable the Google Calendar API
3. Configure an OAuth consent screen
4. Add OAuth scope: https://www.googleapis.com/auth/calendar
5. Create an OAuth Client ID for “Desktop App”
6. Save credentials as local_auth/oauth_configs/gcalendar/oauth.json

Authenticate

python src/servers/gcalendar/main.py auth

Available Tools

list_events

Description: List events from Google Calendar for a specified time range

Parameters:

• calendar_id (string, optional): Calendar ID (defaults to “primary”)
• days (integer, optional): Number of days to look ahead (default: 7)
• max_results (integer, optional): Maximum number of events (default: 10)

Example:

{
  "calendar_id": "primary",
  "days": 30,
  "max_results": 50
}

Returns: List of events with full details

create_event

Description: Create a new event in Google Calendar

Parameters:

• calendar_id (string, optional): Calendar ID (defaults to “primary”)
• summary (string, required): Event title
• start_datetime (string, required): Start date/time (format: “YYYY-MM-DD HH:MM” or “YYYY-MM-DD”)
• end_datetime (string, required): End date/time (format: “YYYY-MM-DD HH:MM” or “YYYY-MM-DD”)
• description (string, optional): Event description
• location (string, optional): Event location
• attendees (array, optional): List of attendee email addresses

Example:

{
  "summary": "Team Meeting",
  "start_datetime": "2024-03-15 14:00",
  "end_datetime": "2024-03-15 15:00",
  "description": "Quarterly planning discussion",
  "location": "Conference Room A",
  "attendees": ["[e-mail]", "[e-mail]"]
}

Returns: Event details with ID and link

update_event

Description: Update an existing event in Google Calendar

Parameters:

• calendar_id (string, optional): Calendar ID (defaults to “primary”)
• event_id (string, required): Event ID to update
• summary (string, optional): New event title
• start_datetime (string, optional): New start date/time
• end_datetime (string, optional): New end date/time
• description (string, optional): New description
• location (string, optional): New location
• attendees (array, optional): New attendee list

Example:

{
  "event_id": "abc123xyz789",
  "summary": "Team Meeting (Rescheduled)",
  "start_datetime": "2024-03-16 14:00",
  "end_datetime": "2024-03-16 15:00"
}

Returns: Updated event details with link

Resources

The Google Calendar server provides calendar and event resources:

List Resources

Provides access to:

• All your calendars
• Upcoming events (next 7 days)

URI Format:

• gcalendar:///{calendar_id} - Specific calendar
• gcalendar:///upcoming - Upcoming events

Read Resource

Reads calendar events with details:

• Event title
• Start and end times
• Location
• Attendees
• Description

Usage Examples

Listing Events

# List upcoming events
events = await call_tool("list_events", {
    "days": 7,
    "max_results": 20
})

# List events from specific calendar
events = await call_tool("list_events", {
    "calendar_id": "[e-mail]",
    "days": 14
})

Creating Events

# Create a meeting with attendees
await call_tool("create_event", {
    "summary": "Project Kickoff",
    "start_datetime": "2024-03-20 10:00",
    "end_datetime": "2024-03-20 11:30",
    "description": "Initial project planning session",
    "location": "Zoom: https://zoom.us/j/123456789",
    "attendees": [
        "[e-mail]",
        "[e-mail]",
        "[e-mail]"
    ]
})

# Create an all-day event
await call_tool("create_event", {
    "summary": "Company Holiday",
    "start_datetime": "2024-12-25",
    "end_datetime": "2024-12-26",
    "description": "Office closed"
})

Updating Events

# First, get the event ID from list_events
events = await call_tool("list_events", {"days": 7})
event_id = events[0]["id"]

# Update the event
await call_tool("update_event", {
    "event_id": event_id,
    "summary": "Project Kickoff (Updated)",
    "location": "Conference Room B"
})

# Reschedule an event
await call_tool("update_event", {
    "event_id": event_id,
    "start_datetime": "2024-03-21 10:00",
    "end_datetime": "2024-03-21 11:30"
})

Date/Time Formats

Timed Events

Use format: YYYY-MM-DD HH:MM (24-hour format)

"start_datetime": "2024-03-15 14:30"  # 2:30 PM
"end_datetime": "2024-03-15 16:00"    # 4:00 PM

All-Day Events

Use format: YYYY-MM-DD

"start_datetime": "2024-03-15"
"end_datetime": "2024-03-16"  # Exclusive end date

Running the Server

Local Development

python src/servers/local.py --server gcalendar --user-id local

Best Practices

1. Time zones: All times are stored in UTC
2. Event IDs: Save event IDs from list_events for later updates
3. All-day events: End date is exclusive (next day)
4. Attendees: Providing attendee emails sends calendar invitations

API Reference

Tool	Purpose	Common Use Cases
list_events	List events	View schedule, find conflicts
create_event	Create event	Schedule meetings, add reminders
update_event	Modify event	Reschedule, update details

Calendar IDs

• primary - Your primary calendar
• Email address - Shared calendars (e.g., [e-mail])
• Calendar ID - Specific calendar ID from list_resources

Related Resources

• Google Calendar API Documentation
• Event Resource Reference