Skip to content

advanced-usage.md

Latest commit

 

History

History
232 lines (163 loc) · 6.71 KB

advanced-usage.md

File metadata and controls

232 lines (163 loc) · 6.71 KB

Advanced Usage Guide

This guide covers advanced features and use cases for the Google Calendar MCP Server.

Multi-Account Support

The server allows you to connect multiple Google accounts simultaneously (e.g., personal, work, family) and interact with all of them seamlessly. See Authentication Guide for setup instructions.

Using Accounts with Tools

All tools accept an optional account parameter. The behavior depends on the tool type:

Account Parameter Behavior

Tool Type Accepts Arrays? account Omitted account: "work" account: ["work", "personal"]
Read-only (list-events, list-calendars, get-freebusy) ✅ Yes Merges ALL accounts Single account only Merges specified accounts
Write (create-event, update-event, delete-event) ❌ No Auto-selects best permission Uses specified account ❌ Error (not supported)
Get (get-event, search-events) ❌ No Auto-selects account with access Uses specified account ❌ Error (not supported)

Auto-selection logic:

  • When account is omitted, the server automatically selects the account with appropriate permissions
  • Write operations require write/owner access
  • Read operations work with any access level (reader, writer, or owner)
  • If no account has the required permissions, you'll get a clear error message

Examples

// Read-only tools: Query all authenticated accounts (auto-merge)
use_tool("list-events", {
  timeMin: "2025-02-01T00:00:00",
  timeMax: "2025-02-01T23:59:59"
  // No account parameter = merges all accounts
});

// Read-only tools: Query specific accounts
use_tool("list-events", {
  account: ["work", "personal"],  // Array supported!
  timeMin: "2025-02-01T00:00:00",
  timeMax: "2025-02-01T23:59:59"
});

// Write tools: Explicitly pick account
use_tool("create-event", {
  calendarId: "team@company.com",
  summary: "Status update",
  account: "work",  // Must be single string, not array
  start: "2025-02-01T10:00:00",
  end: "2025-02-01T11:00:00"
});

// Write tools: Auto-select account (finds account with write access)
use_tool("create-event", {
  calendarId: "team@company.com",
  summary: "Status update",
  // No account parameter = auto-selects account with write permission
  start: "2025-02-01T10:00:00",
  end: "2025-02-01T11:00:00"
});

Calendar Deduplication

The Calendar Registry collects calendars from every account, de-duplicates shared calendars, and tracks the best account to use for read/write operations. Responses include accountAccess arrays so you can see every account that can reach a given calendar.

Batch Operations

List Events from Multiple Calendars

Request events from several calendars simultaneously:

"Show me all events from my work, personal, and team calendars for next week"

The server will:

  1. Query all specified calendars in parallel
  2. Merge and sort results chronologically
  3. Handle different timezones correctly

Batch Event Creation

Create multiple related events:

"Schedule a 3-part training series every Monday at 2pm for the next 3 weeks"

Recurring Events

Modification Scopes

When updating recurring events, you can specify the scope:

  1. This event only: Modify a single instance

    "Move tomorrow's standup to 11am (just this one)"

  2. This and following events: Modify from a specific date forward

    "Change all future team meetings to 30 minutes starting next week"

  3. All events: Modify the entire series

    "Update the location for all weekly reviews to Conference Room B"

Complex Recurrence Patterns

The server supports all Google Calendar recurrence rules:

  • Daily, weekly, monthly, yearly patterns
  • Custom intervals (e.g., every 3 days)
  • Specific days (e.g., every Tuesday and Thursday)
  • End conditions (after N occurrences or by date)

Timezone Handling

  • If no timezone is specified, the server uses your calendar's default timezone
  • You can explicitly set a timezone using the timeZone parameter
  • Proper handling of daylight saving time transitions
  • Support for scheduling across timezones

Availability Checking

Find optimal meeting times:

"Find a 90-minute slot next week when both my work and personal calendars are free, preferably in the afternoon"

Working with Images

Extract Events from Screenshots

"Add this event to my calendar [attach screenshot]"

Supported formats: PNG, JPEG, GIF

The server can extract:

  • Date and time information
  • Event titles and descriptions
  • Location details
  • Attendee lists

Best Practices for Image Recognition

  1. Ensure text is clear and readable
  2. Include full date/time information in the image
  3. Highlight or circle important details
  4. Use high contrast images

Advanced Search

Search Operators

  • By attendee: "meetings with john@example.com"
  • By location: "events at headquarters"
  • By time range: "morning meetings this month"
  • By status: "tentative events this week"

Complex Queries

Combine multiple criteria:

"Find all meetings with the sales team at the main office that are longer than an hour in the next two weeks"

Calendar Analysis

Meeting Patterns

"How much time did I spend in meetings last week?"
"What percentage of my meetings are recurring?"
"Which day typically has the most meetings?"

Performance Optimization

Rate Limiting

Built-in protection against API limits:

  • Automatic retry with exponential backoff in batch operations

Integration Examples

Daily Schedule

"Show me today's events and check for any scheduling conflicts between all my calendars"

Weekly Planning

"Look at next week and suggest the best times for deep work blocks of at least 2 hours"

Meeting Preparation

"For each meeting tomorrow, tell me who's attending, what the agenda is, and what materials I should review"

Security Considerations

Permission Scopes

The server only requests necessary permissions:

  • calendar.events: Full event management
  • Never requests email or profile access
  • No access to other Google services

Token Security

  • Tokens stored locally with owner-only permissions (0600) in ~/.config/google-calendar-mcp/tokens.json
  • Automatic token refresh with durable multi-account storage
  • Credentials never leave your machine (no remote storage)
  • No tokens are written to logs or emitted over stdout/stderr

Debugging

Common Issues

  1. Token refresh failures: Check network connectivity
  2. API quota exceeded: Implement backoff strategies
  3. Timezone mismatches: Ensure consistent timezone usage