{"name":"Calendar MCP","version":"1.0.0","endpoint":"https://calendarmcp.ai/api/mcp","auth":{"type":"bearer","header":"Authorization: Bearer YOUR_API_KEY","description":"Get your API key at https://calendarmcp.ai/dashboard after connecting your Google Calendar."},"docs_url":"https://calendarmcp.ai/docs","notes":{"timed_vs_allday":"Timed events use startDateTime/endDateTime (ISO 8601). All-day events use startDate/endDate (YYYY-MM-DD). End date is exclusive for all-day events. Never mix date and dateTime on the same event.","search_limitation":"Text search (query/q param) may not work on non-primary calendars due to a Google Calendar API limitation.","color_ids":"Color IDs are 1-11. See https://developers.google.com/calendar/api/v3/reference/colors/get","multi_account":"One API key can hold multiple Google accounts — any mix of OAuth-connected accounts and service-account-shared calendars. Tools that omit calendarId fan out across every enabled calendar the key can read.","permissions":"Per-calendar Read/Write grants are enforced server-side. Tools that read require Read; tools that write require Write. Denied or unknown calendars return a PermissionError with a clear message. Call list_calendars at runtime to discover what the key can do.","service_account_attendees":"Service-account-connected calendars cannot invite or change attendees — Google does not allow service accounts to dispatch invites on personal calendars. create_event, update_event, and manage_attendees reject attendee changes on SA calendars. Connect the same Google account via OAuth to manage attendees.","advanced_protection":"Google Advanced Protection accounts cannot OAuth into third-party apps at all. AP users must use the service-account sharing flow. See /advanced-protection for the full setup."},"tools":[{"name":"list_events","description":"List events from one or more Google Calendars within a time range. Auto-paginates up to 2500 results. When no calendarId is provided, queries every enabled calendar the API key can read — across every connected Google account — in parallel (one call per connection) and merges results sorted by start time.","requires":"Read on the target calendar.","parameters":{"calendarId":{"type":"string","required":false,"description":"Calendar ID. Omit to fan out across every enabled calendar this API key can read."},"timeMin":{"type":"string","required":false,"description":"Start of time range (ISO 8601)"},"timeMax":{"type":"string","required":false,"description":"End of time range (ISO 8601)"},"maxResults":{"type":"number","required":false,"default":10,"description":"Max events (1-2500). Auto-paginates internally."},"query":{"type":"string","required":false,"description":"Free text search. May not work on non-primary calendars."},"singleEvents":{"type":"boolean","required":false,"default":true,"description":"Expand recurring events into instances."},"orderBy":{"type":"string","required":false,"default":"startTime","enum":["startTime","updated"]},"pageToken":{"type":"string","required":false,"description":"Pagination token from previous response."}},"example":{"tool":"list_events","arguments":{"timeMin":"2026-04-01T00:00:00Z","timeMax":"2026-04-30T23:59:59Z","maxResults":50}},"returns":{"type":"array","items":"Event objects: { id, summary, description, location, start, end, status, htmlLink, organizer, attendees, recurrence, reminders, transparency, visibility, colorId, calendarId?, calendarName? }"}},{"name":"get_event","description":"Get full details of a specific calendar event by its ID.","requires":"Read on the target calendar.","parameters":{"calendarId":{"type":"string","required":false},"eventId":{"type":"string","required":true,"description":"The event ID to retrieve."}},"example":{"tool":"get_event","arguments":{"eventId":"abc123def456"}},"returns":{"type":"object","description":"Single event object with all fields."}},{"name":"create_event","description":"Create a new calendar event with attendees, location, reminders, recurrence, transparency, visibility, and color.","requires":"Write on the target calendar. Attendees are rejected on service-account-connected calendars (use OAuth for invites).","parameters":{"calendarId":{"type":"string","required":false},"summary":{"type":"string","required":true,"description":"Event title."},"description":{"type":"string","required":false},"location":{"type":"string","required":false},"startDateTime":{"type":"string","required":false,"description":"ISO 8601. For timed events."},"endDateTime":{"type":"string","required":false,"description":"ISO 8601. For timed events."},"startDate":{"type":"string","required":false,"description":"YYYY-MM-DD. For all-day events."},"endDate":{"type":"string","required":false,"description":"YYYY-MM-DD (exclusive). For all-day events."},"timeZone":{"type":"string","required":false},"attendees":{"type":"string[]","required":false,"description":"Email addresses."},"reminders":{"type":"object","required":false,"description":"{ useDefault: boolean, overrides?: [{ method: \"email\"|\"popup\", minutes: number }] }"},"recurrence":{"type":"string[]","required":false,"description":"RRULE format."},"transparency":{"type":"string","required":false,"enum":["opaque","transparent"],"description":"\"opaque\" = busy (default), \"transparent\" = free."},"visibility":{"type":"string","required":false,"enum":["default","public","private","confidential"]},"colorId":{"type":"string","required":false,"description":"1-11."}},"example":{"tool":"create_event","arguments":{"summary":"Team Standup","startDateTime":"2026-04-20T09:00:00-07:00","endDateTime":"2026-04-20T09:30:00-07:00","timeZone":"America/Denver","attendees":["alice@example.com"],"reminders":{"useDefault":false,"overrides":[{"method":"popup","minutes":10}]}}},"returns":{"type":"object","description":"Created event object."}},{"name":"update_event","description":"Update an existing event. Partial PATCH — only provide fields to change.","requires":"Write on the target calendar. Attendee changes are rejected on service-account-connected calendars (use OAuth).","parameters":{"calendarId":{"type":"string","required":false},"eventId":{"type":"string","required":true},"summary":{"type":"string","required":false},"description":{"type":"string","required":false},"location":{"type":"string","required":false},"startDateTime":{"type":"string","required":false},"endDateTime":{"type":"string","required":false},"startDate":{"type":"string","required":false},"endDate":{"type":"string","required":false},"timeZone":{"type":"string","required":false},"status":{"type":"string","required":false,"enum":["confirmed","tentative","cancelled"]},"reminders":{"type":"object","required":false,"description":"{useDefault: false, overrides: []} to suppress all."},"transparency":{"type":"string","required":false,"enum":["opaque","transparent"]},"visibility":{"type":"string","required":false,"enum":["default","public","private","confidential"]},"colorId":{"type":"string","required":false},"attendees":{"type":"string[]","required":false,"description":"Replaces existing attendees."},"recurrence":{"type":"string[]","required":false}},"example":{"tool":"update_event","arguments":{"eventId":"abc123","reminders":{"useDefault":false,"overrides":[]},"transparency":"transparent"}},"returns":{"type":"object","description":"Updated event object."}},{"name":"batch_update_events","description":"Update multiple events in one call. Max 50. Concurrent execution.","requires":"Write on the target calendar.","parameters":{"calendarId":{"type":"string","required":false,"description":"Applies to all events in the batch."},"updates":{"type":"array","required":true,"max":50,"description":"Array of {eventId, ...fields}. Each supports same fields as update_event.","items":{"eventId":{"type":"string","required":true},"summary":{"type":"string","required":false},"description":{"type":"string","required":false},"location":{"type":"string","required":false},"startDateTime":{"type":"string","required":false},"endDateTime":{"type":"string","required":false},"startDate":{"type":"string","required":false},"endDate":{"type":"string","required":false},"timeZone":{"type":"string","required":false},"status":{"type":"string","required":false},"reminders":{"type":"object","required":false},"transparency":{"type":"string","required":false},"visibility":{"type":"string","required":false},"colorId":{"type":"string","required":false}}}},"example":{"tool":"batch_update_events","arguments":{"updates":[{"eventId":"evt1","reminders":{"useDefault":false,"overrides":[]}},{"eventId":"evt2","reminders":{"useDefault":false,"overrides":[]}},{"eventId":"evt3","colorId":"5"}]}},"returns":{"type":"string","description":"\"X succeeded, Y failed\" with event IDs and error details."}},{"name":"delete_event","description":"Delete a calendar event.","requires":"Write on the target calendar.","parameters":{"calendarId":{"type":"string","required":false},"eventId":{"type":"string","required":true}},"example":{"tool":"delete_event","arguments":{"eventId":"abc123"}},"returns":{"type":"string","description":"Confirmation message."}},{"name":"quick_add_event","description":"Create event from natural language. Google parses date, time, title, location.","requires":"Write on the target calendar.","parameters":{"calendarId":{"type":"string","required":false},"text":{"type":"string","required":true,"description":"e.g. \"Lunch with Alice tomorrow at noon at Cafe Rio\""}},"example":{"tool":"quick_add_event","arguments":{"text":"Dentist appointment Friday at 2pm"}},"returns":{"type":"object","description":"Created event object."}},{"name":"list_calendars","description":"List every calendar this API key can access across every connected Google account, with its enabled flag, per-calendar read/write permissions, and which kind of connection backs it (OAuth or service account). Use this for runtime permission discovery before attempting other tool calls.","parameters":{},"example":{"tool":"list_calendars","arguments":{}},"returns":{"type":"array","items":"{ id, summary, enabled, canRead, canWrite, connectionKind: \"oauth\" | \"service_account\" }"}},{"name":"find_free_time","description":"Query free/busy information for one or more calendars.","requires":"Read on each target calendar. Fans out across connections.","parameters":{"calendarIds":{"type":"string[]","required":false},"timeMin":{"type":"string","required":true,"description":"ISO 8601"},"timeMax":{"type":"string","required":true,"description":"ISO 8601"}},"example":{"tool":"find_free_time","arguments":{"timeMin":"2026-04-21T08:00:00-07:00","timeMax":"2026-04-21T18:00:00-07:00"}},"returns":{"type":"array","description":"Busy slots per calendar with start/end times."}},{"name":"manage_attendees","description":"Add or remove attendees without replacing the full list.","requires":"Write on the target calendar AND an OAuth-connected account. Rejects service-account-connected calendars with a clear error (Google does not allow SAs to dispatch invites on personal calendars).","parameters":{"calendarId":{"type":"string","required":false},"eventId":{"type":"string","required":true},"addAttendees":{"type":"string[]","required":false},"removeAttendees":{"type":"string[]","required":false}},"example":{"tool":"manage_attendees","arguments":{"eventId":"abc123","addAttendees":["charlie@example.com"],"removeAttendees":["dave@example.com"]}},"returns":{"type":"object","description":"Updated event object."}}],"common_patterns":[{"name":"Suppress all reminders","example":{"tool":"update_event","arguments":{"eventId":"EVENT_ID","reminders":{"useDefault":false,"overrides":[]}}}},{"name":"Mark as free (not blocking)","example":{"tool":"update_event","arguments":{"eventId":"EVENT_ID","transparency":"transparent"}}},{"name":"Bulk suppress reminders","example":{"tool":"batch_update_events","arguments":{"updates":[{"eventId":"evt1","reminders":{"useDefault":false,"overrides":[]}},{"eventId":"evt2","reminders":{"useDefault":false,"overrides":[]}}]}}},{"name":"Create all-day hotel stay (3 nights, Apr 15-17)","example":{"tool":"create_event","arguments":{"summary":"🏨 Hilton Downtown","startDate":"2026-04-15","endDate":"2026-04-18","description":"Confirmation: ABC123\nCheck-in: 3pm\nCheck-out: 11am","reminders":{"useDefault":false,"overrides":[]},"transparency":"transparent"}}},{"name":"Scan full month","example":{"tool":"list_events","arguments":{"timeMin":"2026-04-01T00:00:00Z","timeMax":"2026-04-30T23:59:59Z","maxResults":500}}}]}