Google Calendar MCP Skill

FastMCP server for Google Calendar management.

Quick Start

# Start MCP server
python src/mcp_servers/google_calendar_server.py

MCP Tools

1. list_events(calendar_id, max_results, time_min, time_max)

   - List upcoming events

2. create_event(summary, start_time, end_time, description, location, attendees)

   - Create new event

3. update_event(event_id, summary, description, location)

   - Modify existing event

4. delete_event(event_id)

   - Cancel event

Production Gotchas

Timezone Handling

All times are stored in UTC by default. Client must convert:

# Server always uses UTC
'start': {
    'dateTime': start_time,
    'timeZone': 'UTC',  # Always UTC internally
}

# Convert for user display
from datetime import timezone
local_time = utc_time.astimezone(timezone.utc)

ISO Format Required

Time parameters MUST be ISO 8601 format:

# ✓ CORRECT
create_event(start_time="2026-01-30T10:00:00")

# ✗ WRONG - Natural language
create_event(start_time="tomorrow 10am")

# ✗ WRONG - Missing T separator
create_event(start_time="2026-01-30 10:00:00")

Calendar ID Conventions

• 'primary'

  - User's main calendar (default)
• Email address - Shared calendar access
• Calendar ID from Google - For secondary calendars

Attendees Are Optional But Important

Omitting attendees creates a private event:

# Private event (no notifications)
create_event(summary="Focus time", start_time=..., end_time=...)

# Meeting with notifications
create_event(
    summary="Team sync",
    start_time=...,
    end_time=...,
    attendees=["alice@example.com", "bob@example.com"]
)

Separate Token File

Calendar uses different OAuth token than Gmail:

• token_calendar.json

  - Calendar access

• token.json

  /

  token_email.json

  - Gmail access

Event ID Required for Updates

You must first retrieve the event ID before updating:

# ✗ FAILS - No ID
update_event(summary="New title")

# ✓ WORKS - Get ID from list_events first
events = list_events()
event_id = events[0]['id']
update_event(event_id=event_id, summary="New title")

Configuration

Required in

config/

:

• credentials.json

  - Google OAuth credentials

• token_calendar.json

  - Calendar OAuth token

OAuth Scopes:

SCOPES = ['https://www.googleapis.com/auth/calendar']

Setup

1. Enable Google Calendar API

1. Go to Google Cloud Console
2. Enable "Google Calendar API"
3. Create OAuth credentials (Desktop app)
4. Download as

   config/credentials.json

2. First Run

python src/mcp_servers/google_calendar_server.py

This opens a browser for OAuth consent. Token saves to

token_calendar.json

.

Rate Limits

Google Calendar API limits:

• 1,000,000 queries per day
• 500 queries per 100 seconds per user

Not typically a concern for personal use.

Audit Logging

All operations logged via

utils/audit_logger.py

:

• Domain:

  AuditDomain.PERSONAL

• Actions:

  calendar.list_events

  ,

  calendar.create_event

  , etc.

Verification

Run:

python scripts/verify.py

Related Skills

• watching-gmail

  - Detect meeting requests in emails

• digital-fte-orchestrator

  - Process calendar-related tasks