Summary
Connects Claude to the Google Calendar API with full OAuth proxy support, letting you list, create, update, and delete events without storing credentials server-side. Handles the complete calendar workflow: RSVP to invites, find free/busy times, manage recurring events, control calendar sharing via ACLs, and even subscribe to shared calendars. The architecture is clever: it proxies OAuth flows to Google while encoding your callback URL in state, so tokens stay between you and Google. Ships with 15+ tools covering calendars, events, availability queries, and color customization. Reach for this when you want Claude to schedule meetings, block focus time, or answer "what's free Thursday afternoon" without leaving the conversation.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
29 tools
GOOGLECALENDAR_ACL_PATCHUpdates an access control rule for a calendar using patch semantics (partial update). This allows modifying specific fields without affecting other properties. Note: Each patch request consumes three quota units. For domain-type ACL rules, if PATCH fails with 500 error, this a...5 params
Updates an access control rule for a calendar using patch semantics (partial update). This allows modifying specific fields without affecting other properties. Note: Each patch request consumes three quota units. For domain-type ACL rules, if PATCH fails with 500 error, this a...
Parameters* required
rolestringThe role assigned to the scope. Possible values are: "none" - Provides no access; "freeBusyReader" - Provides read access to free/busy information; "reader" - Provides read access to the calendar (private events appear but details are hidden); "writer" - Provides read and write access to the calendar (private events and details are visible); "owner" - Provides ownership of the calendar (all permissions of writer plus ability to see and manipulate ACLs).
Examples:
"reader"
"writer"
"owner"
scopevalueThe extent to which calendar access is granted by this ACL rule. Optional for patch operations.
rule_idstringACL rule identifier. This is typically in the format 'type:value', such as 'user:email@example.com' or 'group:group@example.com'.
Examples:
"user:test.user@example.com"
"group:team@example.com"
"domain:example.com"
calendar_idstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Examples:
"primary"
"example@group.calendar.google.com"
send_notificationsbooleanWhether to send notifications about the calendar sharing change. Note that there are no notifications on access removal. Optional. The default is True.
Examples:
true
false
GOOGLECALENDAR_CALENDAR_LIST_INSERTInserts an existing calendar into the user's calendar list.10 params
Inserts an existing calendar into the user's calendar list.
Parameters* required
idstringThe identifier of the calendar to insert.
Example: "examplecalendar@group.calendar.google.com"
hiddenbooleanWhether the calendar has been hidden from the list. Default is False.
color_idstringThe color of the calendar. This is an ID referring to an entry in the calendarCore color palette.
Example: "1"
selectedbooleanWhether the calendar is selected and visible in the calendar list. Default is True.
background_colorstringThe background color of the calendar in the Web UI. (Hexadecimal color code)
Example: "#000000"
color_rgb_formatbooleanWhether to use the foregroundColor and backgroundColor fields to write the calendar colors (RGB). If this feature is used, the index-based colorId field will be set to the best matching option automatically. Optional. The default is False.
foreground_colorstringThe foreground color of the calendar in the Web UI. (Hexadecimal color code)
Example: "#FFFFFF"
summary_overridestringThe summary that the authenticated user has set for this calendar.
default_remindersvalueThe default reminders that the authenticated user has for this calendar.
notification_settingsvalueThe notifications that the authenticated user is receiving for this calendar.
GOOGLECALENDAR_CALENDAR_LIST_UPDATEUpdates an existing entry on the user\'s calendar list.10 params
Updates an existing entry on the user\'s calendar list.
Parameters* required
hiddenbooleanWhether calendar is hidden.
Examples:
true
false
colorIdstringID for calendar color from colors endpoint.
Example: "17"
selectedbooleanWhether calendar content shows in UI.
Examples:
true
false
calendar_idstringCalendar identifier. Must be an actual calendar ID (e.g., calendar email address like "examplecalendar@group.calendar.google.com"). The "primary" alias is not valid for calendarList.update - use the actual calendar ID.
Example: "examplecalendar@group.calendar.google.com"
colorRgbFormatbooleanWhether to use RGB for foreground/background colors.
Examples:
true
false
backgroundColorstringHex color for calendar background.
Example: "#0088aa"
foregroundColorstringHex color for calendar foreground.
Example: "#ffffff"
summaryOverridestringUser-set summary for the calendar.
Example: "My Work Calendar"
defaultRemindersvalueList of default reminders.
notificationSettingsvalueNotification settings for the calendar.
GOOGLECALENDAR_CALENDARS_DELETEDeletes a secondary calendar. Use calendars.clear for clearing all events on primary calendars.1 params
Deletes a secondary calendar. Use calendars.clear for clearing all events on primary calendars.
Parameters* required
calendar_idstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Examples:
"primary"
"example_calendar_id@group.calendar.google.com"
GOOGLECALENDAR_CALENDARS_UPDATEUpdates metadata for a calendar.5 params
Updates metadata for a calendar.
Parameters* required
summarystringTitle of the calendar.
locationstringGeographic location of the calendar as free-form text. Optional.
timeZonestringThe time zone of the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich".) Optional.
calendarIdstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
descriptionstringDescription of the calendar. Optional.
GOOGLECALENDAR_CLEAR_CALENDARClears a primary calendar. This operation deletes all events associated with the primary calendar of an account.1 params
Clears a primary calendar. This operation deletes all events associated with the primary calendar of an account.
Parameters* required
calendar_idstringCalendar identifier. To retrieve calendar IDs call the `calendarList.list` method. If you want to access the primary calendar of the currently logged in user, use the "`primary`" keyword.
Example: "primary"
GOOGLECALENDAR_CREATE_EVENTCreate a Google Calendar event using `start_datetime` plus `event_duration_hour` and `event_duration_minutes` fields to derive the end time. Requires calendar write access. The organizer is added as an attendee unless `exclude_organizer` is True. Example request to create even...23 params
Create a Google Calendar event using `start_datetime` plus `event_duration_hour` and `event_duration_minutes` fields to derive the end time. Requires calendar write access. The organizer is added as an attendee unless `exclude_organizer` is True. Example request to create even...
Parameters* required
summarystringSummary (title) of the event.
locationstringGeographic location of the event as free-form text.
timezonestringIANA timezone name (e.g., 'America/New_York'). Required if datetime is naive. For recurring events, start and end must include a timeZone. If not provided, UTC is used. If datetime includes timezone info (Z or offset), this field is optional and defaults to UTC.
attendeesvalueList of attendee emails (strings).
eventTypestringType of the event, immutable post-creation. 'workingLocation' (REQUIRES Google Workspace Enterprise). Note: 'fromGmail' events cannot be created via API.one of
birthday · default · focusTime · outOfOffice · workingLocationdefault: defaultrecurrencevalueList of RRULE, EXRULE, RDATE, EXDATE lines for recurring events. Supported frequencies: DAILY, WEEKLY, MONTHLY, YEARLY. For recurring events, start.timeZone and end.timeZone must be present. Provide an empty list to remove recurrence so the event becomes non-recurring.
visibilitystringEvent visibility: 'default', 'public', 'private', or 'confidential'.one of
default · public · private · confidentialdefault: defaultcalendar_idstringTarget calendar: 'primary' for the user's main calendar, or the calendar's email address. Must be provided in snake_case format.
Examples:
"primary"
"user@example.com"
"abcdefghijklmnopqrstuvwxyz@group.calendar.google.com"default: primary
descriptionstringDescription of the event. Can contain HTML. Optional. Must be omitted for 'birthday' event type.
send_updatesbooleanDefaults to True. Whether to send updates to the attendees.
transparencystring'opaque' (busy) or 'transparent' (available).one of
opaque · transparentdefault: opaquestart_datetimestringEvent start time in format YYYY-MM-DDTHH:MM:SS (no fractional seconds, no 'Z', no timezone offsets). Examples: '2025-01-16T13:00:00' or '2025-01-16T13:00'. Timezone info (Z, +, -) will be automatically stripped if provided.
exclude_organizerbooleanIf True, the organizer will NOT be added as an attendee. Default is False (organizer is included).default: false
guests_can_modifybooleanIf True, guests can modify the event.default: false
birthdayPropertiesvalueProperties for birthday events.
create_meeting_roombooleanIf true, a Google Meet link is created and added to the event. CRITICAL: As of 2024, this REQUIRES a paid Google Workspace account ($13+/month). Personal Gmail accounts will fail with 'Invalid conference type value' error. Solutions: 1) Upgrade to Workspace, 2) Use domain-wide delegation with Workspace user, 3) Use the new Google Meet REST API, or 4) Create events without conferences. See https://github.com/googleapis/google-api-nodejs-client/issues/3234
event_duration_hourintegerNumber of hours (0-24). Increase by 1 here rather than passing 60 in `event_duration_minutes`default: 0
focusTimePropertiesvalueProperties for focusTime events. REQUIRES Google Workspace Enterprise account with Focus Time feature enabled.
guestsCanInviteOthersbooleanWhether attendees other than the organizer can invite others to the event.
outOfOfficePropertiesvalueProperties for outOfOffice events.
event_duration_minutesintegerDuration in minutes (0-59 ONLY). NEVER use 60+ minutes - use event_duration_hour=1 instead. Maximum value is 59. Combined duration (hours + minutes) must be greater than 0.default: 30
guestsCanSeeOtherGuestsbooleanWhether attendees other than the organizer can see who the event's attendees are.
workingLocationPropertiesvalueProperties for workingLocation events. REQUIRES Google Workspace Enterprise.
Constraints discovered from testing:
- Must set transparency='transparent' and visibility='public'
- Description must be omitted
- Depending on 'type', include one of 'homeOffice', 'officeLocation', or 'customLocation'
GOOGLECALENDAR_DELETE_EVENTDeletes a specified event by `event_id` from a Google Calendar (`calendar_id`); this action is idempotent and raises a 404 error if the event is not found.2 params
Deletes a specified event by `event_id` from a Google Calendar (`calendar_id`); this action is idempotent and raises a 404 error if the event is not found.
Parameters* required
event_idstringUnique identifier of the event to delete, typically obtained upon event creation.
calendar_idstringIdentifier of the Google Calendar (e.g., email address, specific ID, or 'primary' for the authenticated user's main calendar) from which the event will be deleted.
Examples:
"primary"
"user@example.com"
"abcsomecalendarid@group.calendar.google.com"default: primary
GOOGLECALENDAR_DUPLICATE_CALENDARCreates a new, empty Google Calendar with the specified title (summary).1 params
Creates a new, empty Google Calendar with the specified title (summary).
Parameters* required
summarystringTitle for the new Google Calendar to be created. Required and must be a non-empty string.
Examples:
"Project Alpha Tasks"
"Marketing Team Q4"
"Personal Appointments"
GOOGLECALENDAR_EVENTS_INSTANCESReturns instances of the specified recurring event.10 params
Returns instances of the specified recurring event.
Parameters* required
eventIdstringRecurring event identifier.
Example: "a1b2c3d4e5f6g7h8i9j0k1l2m3"
timeMaxstringUpper bound (exclusive) for an event's start time to filter by. Optional. The default is not to filter by start time. Must be an RFC3339 timestamp with mandatory time zone offset.
Example: "2024-07-31T23:59:59Z"
timeMinstringLower bound (inclusive) for an event's end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset.
Example: "2024-07-01T00:00:00Z"
timeZonestringTime zone used in the response. Optional. The default is the time zone of the calendar.
Examples:
"America/Los_Angeles"
"Europe/London"
pageTokenstringToken specifying which result page to return. Optional.
calendarIdstringCalendar identifier. To retrieve calendar IDs call the `calendarList.list` method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Examples:
"primary"
"example.calendar.id@group.calendar.google.com"
maxResultsvalueMaximum number of events returned on one result page. By default the value is 250 events. The page size can never be larger than 2500 events. Optional.
Examples:
100
250
showDeletedbooleanWhether to include deleted events (with status equals "cancelled") in the result. Cancelled instances of recurring events will still be included if `singleEvents` is False. Optional. The default is False.
Examples:
true
false
maxAttendeesvalueThe maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional.
Examples:
5
10
originalStartstringThe original start time of the instance in the result. Optional.
Example: "2024-07-15T10:00:00Z"
GOOGLECALENDAR_EVENTS_LISTReturns events on the specified calendar.19 params
Returns events on the specified calendar.
Parameters* required
qstringFree text search terms to find events that match these terms in various fields. Optional.
iCalUIDstringSpecifies an event ID in the iCalendar format to be provided in the response. Optional. Use this if you want to search for an event by its iCalendar ID.
orderBystringThe order of the events returned in the result. Optional. The default is an unspecified, stable order. Acceptable values are: "startTime", "updated". When set to "startTime", singleEvents must be true. The action automatically sets singleEvents=true when orderBy='startTime'.
timeMaxstringUpper bound (exclusive) for an event's start time to filter by. Optional. If unset, no start-time upper bound is applied. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). Milliseconds may be provided but are ignored. If timeMin is set, timeMax must be greater than timeMin.
timeMinstringLower bound (exclusive) for an event's end time to filter by. Optional. If unset, no end-time lower bound is applied. Must be an RFC3339 timestamp with mandatory time zone offset (e.g., 2011-06-03T10:00:00-07:00 or 2011-06-03T10:00:00Z). Milliseconds may be provided but are ignored. If timeMax is set, timeMin must be smaller than timeMax.
timeZonestringTime zone used in the response. Optional. Use an IANA time zone identifier (e.g., America/Los_Angeles). Defaults to the user's primary time zone. Offsets (e.g., '-03:00', 'UTC+0') and abbreviations (e.g., 'IST', 'PST') are invalid.
pageTokenstringToken specifying which result page to return. Optional.
syncTokenstringToken from nextSyncToken to return only entries changed since the last list. Cannot be combined with iCalUID, orderBy, privateExtendedProperty, q, sharedExtendedProperty, timeMin, timeMax, or updatedMin. Deletions since the previous list are always included; showDeleted cannot be false in this mode. The action automatically removes conflicting parameters when syncToken is provided.
calendarIdstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "primary"
eventTypesstringEvent types to return. Optional. This parameter can be repeated multiple times to return events of different types. If unset, returns all event types. Acceptable values are: "birthday", "default", "focusTime", "fromGmail", "outOfOffice", "workingLocation".
maxResultsvalueMaximum number of events returned on one result page. The number of events in the resulting page may be less than this value, or none at all, even if there are more events matching the query. Incomplete pages can be detected by a non-empty nextPageToken field in the response. By default the value is 250 events. The page size can never be larger than 2500 events. Optional.
updatedMinstringLower bound for an event's last modification time (RFC3339). When specified, entries deleted since this time are always included regardless of showDeleted. Optional.
showDeletedbooleanInclude cancelled events (status="cancelled"). Optional; default is false. This surfaces cancelled (soft-deleted) events, not items in the Trash. When syncToken or updatedMin is used, deletions since those markers are included regardless of showDeleted. Recurring interaction: if singleEvents=false and showDeleted=false, cancelled instances of a recurring series may still be included; if showDeleted=true and singleEvents=true, only single deleted instances (not parent series) are returned.
maxAttendeesvalueThe maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional. Must be >= 1 if provided.
singleEventsbooleanWhether to expand recurring events into instances and only return single one-off events and instances of recurring events. Optional. The default is False.
alwaysIncludeEmailbooleanDeprecated and ignored.
showHiddenInvitationsbooleanWhether to include hidden invitations in the result. Optional. The default is False. Hidden invitations are events where your attendee entry has responseStatus='needsAction' and attendees[].self==true. When true, such invitations are included.
sharedExtendedPropertystringExtended properties constraint specified as propertyName=value. Matches only shared properties. This parameter might be repeated multiple times to return events that match all given constraints.
privateExtendedPropertystringExtended properties constraint specified as propertyName=value. Matches only private properties. This parameter might be repeated multiple times to return events that match all given constraints.
GOOGLECALENDAR_EVENTS_MOVEMoves an event to another calendar, i.e., changes an event's organizer.4 params
Moves an event to another calendar, i.e., changes an event's organizer.
Parameters* required
event_idstringEvent identifier. To retrieve event identifiers call the events.list method.
Example: "7cbh8j70fer2s71jgm1bmeb0f1"
calendar_idstringCalendar identifier of the source calendar. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "primary"
destinationstringCalendar identifier of the destination calendar. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "secondaryCalendarId"
send_updatesvalueGuests who should receive notifications about the change of the event's organizer. Acceptable values are: "all": Notifications are sent to all guests. "externalOnly": Notifications are sent to non-Google Calendar guests only. "none": No notifications are sent. This is the default value if left unspecified.
Examples:
"all"
"externalOnly"
"none"
GOOGLECALENDAR_EVENTS_WATCHWatch for changes to Events resources.7 params
Watch for changes to Events resources.
Parameters* required
idstringA UUID or similar unique string that identifies this channel.
Example: "01234567-89ab-cdef-0123456789ab"
typestringThe type of delivery mechanism used for this channel.
Example: "web_hook"default: web_hook
tokenstringAn arbitrary string delivered to the target address with each notification delivered over this channel. Optional.
Example: "target=myApp-myCalendarChannelDest"
paramsvalueAdditional parameters controlling delivery channel behavior. Optional.
addressstringThe address where notifications are delivered for this channel.
Example: "https://example.com/notifications"
payloadbooleanA Boolean value to indicate whether payload is wanted. Optional.
calendarIdstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "primary"
GOOGLECALENDAR_FIND_EVENTFinds events in a specified Google Calendar using text query, time ranges (event start/end, last modification), and event types; ensure `timeMin` is not chronologically after `timeMax` if both are provided.11 params
Finds events in a specified Google Calendar using text query, time ranges (event start/end, last modification), and event types; ensure `timeMin` is not chronologically after `timeMax` if both are provided.
Parameters* required
querystringFree-text search terms to find events. This query is matched against various event fields including summary, description, location, attendees' details (displayName, email), and organizer's details.
Examples:
"Project Alpha Review"
"Birthday Party"
"Q3 Planning session"
timeMaxstringUpper bound (exclusive) for an event's start time to filter by. Only events starting before this time are included. Accepts multiple formats:
1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z')
2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00')
3. Simple datetime string (e.g., '2024-12-06 13:00:00')
Examples:
"2024-12-31T23:59:59Z"
"2025-01-01 10:00:00"
timeMinstringLower bound (exclusive) for an event's end time to filter by. Only events ending after this time are included. Accepts multiple formats:
1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z')
2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00')
3. Simple datetime string (e.g., '2024-12-06 13:00:00')
Examples:
"2024-01-01T00:00:00Z"
"2024-06-15 09:00:00"
order_bystringOrder of events: 'startTime' (ascending by start time) or 'updated' (ascending by last modification time). Note: 'startTime' requires single_events=true. Use 'updated' if you need to include recurring masters (e.g., cancelled series).
Examples:
"startTime"
"updated"
page_tokenstringToken from a previous response's `nextPageToken` to fetch the subsequent page of results.
calendar_idstringIdentifier of the Google Calendar to query. Use 'primary' for the primary calendar of the authenticated user, an email address for a specific user's calendar, or a calendar ID for other calendars.
Examples:
"primary"
"user@example.com"
"abc...@group.calendar.google.com"default: primary
event_typesarrayEvent types to include. Supported values: 'birthday', 'default', 'focusTime', 'outOfOffice', 'workingLocation'.
Examples:
"default"
"focusTime"
"outOfOffice"
"birthday"
"workingLocation"
max_resultsintegerMaximum number of events per page (1-2500).default: 10
updated_minstringLower bound (exclusive) for an event's last modification time to filter by. Only events updated after this time are included. When specified, events deleted since this time are also included, regardless of the `show_deleted` parameter. Accepts multiple formats:
1. RFC3339 timestamp (e.g., '2024-12-06T13:00:00Z')
2. Comma-separated date/time parts (e.g., '2024,12,06,13,00,00')
3. Simple datetime string (e.g., '2024-12-06 13:00:00')
Example: "2024-07-01T00:00:00Z"
show_deletedbooleanInclude events whose status is 'cancelled'. This surfaces cancelled/deleted events, not a separate 'trash' view. Behavior with recurring events: when single_events=true, only individual cancelled instances are returned (the recurring master is omitted); to include cancelled recurring masters, set single_events=false. If updated_min is provided, events deleted since that time are included regardless of this flag.
single_eventsbooleanWhen true, recurring event series are expanded into their individual instances. When false, only the recurring master events are returned. Note: Ordering by 'startTime' requires singleEvents=true. For large calendars, it is strongly recommended to specify both timeMin and timeMax to limit the expansion window and improve performance.default: true
GOOGLECALENDAR_FIND_FREE_SLOTSFinds both free and busy time slots in Google Calendars for specified calendars within a defined time range (defaults to the current day UTC if `time_min`/`time_max` are omitted). Returns busy intervals enriched with event details and calculates free slots by finding gaps betw...6 params
Finds both free and busy time slots in Google Calendars for specified calendars within a defined time range (defaults to the current day UTC if `time_min`/`time_max` are omitted). Returns busy intervals enriched with event details and calculates free slots by finding gaps betw...
Parameters* required
itemsarrayList of calendar identifiers to query for free/busy information. Each item must be a valid calendar identifier: 'primary' for the user's main calendar, a user/calendar email (e.g., user@example.com), or a calendar ID ending with a Google Calendar domain (e.g., ...@group.calendar.google.com). Only calendars accessible to the authenticated account are allowed. All identifiers are validated; if any is invalid or not found, the action returns an error.
Examples:
"primary"
"user@example.com"
"unique_calendar_id@group.calendar.google.com"
time_maxstringEnd datetime for the query interval. Accepts ISO, comma-separated, or simple datetime formats. If provided without an explicit timezone, it is interpreted in the specified `timezone`. Maximum span between time_min and time_max is approximately 90 days per Google Calendar freeBusy API limit.
Examples:
"2024-12-06T18:00:00Z"
"2024,12,06,18,00,00"
"2024-12-06 18:00:00"
time_minstringStart datetime for the query interval. Accepts ISO, comma-separated, or simple datetime formats. If provided without an explicit timezone, it is interpreted in the specified `timezone`. Maximum span between time_min and time_max is approximately 90 days per Google Calendar freeBusy API limit.
Examples:
"2024-12-06T13:00:00Z"
"2024,12,06,13,00,00"
"2024-12-06 13:00:00"
timezonestringIANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Determines how naive `time_min`/`time_max` are interpreted and the timezone used in the response for `timeMin`, `timeMax`, busy periods, and calculated free slots.
Examples:
"UTC"
"America/New_York"
"Europe/Berlin"default: UTC
group_expansion_maxintegerMaximum calendar identifiers to return for a single group; exceeding this causes an error. Max allowed: 100.default: 100
calendar_expansion_maxintegerMaximum calendars for which FreeBusy information is provided. Max allowed: 50.default: 50
GOOGLECALENDAR_FREE_BUSY_QUERYReturns free/busy information for a set of calendars.6 params
Returns free/busy information for a set of calendars.
Parameters* required
itemsarrayList of calendars and/or groups to query.
timeMaxstringThe end of the interval for the query formatted as per RFC3339.
timeMinstringThe start of the interval for the query formatted as per RFC3339.
timeZonestringTime zone used in the response. Optional. The default is UTC.
groupExpansionMaxvalueMaximal number of calendar identifiers to be provided for a single group. Optional. An error is returned for a group with more members than this value. Maximum value is 100.
calendarExpansionMaxvalueMaximal number of calendars for which FreeBusy information is to be provided. Optional. Maximum value is 50.
GOOGLECALENDAR_GET_CALENDARRetrieves a specific Google Calendar, identified by `calendar_id`, to which the authenticated user has access.1 params
Retrieves a specific Google Calendar, identified by `calendar_id`, to which the authenticated user has access.
Parameters* required
calendar_idstringIdentifier of the Google Calendar to retrieve. 'primary' (the default) represents the user's main calendar; other valid identifiers include the calendar's email address.
Examples:
"primary"
"user@example.com"
"en.usa#holiday@group.v.calendar.google.com"default: primary
GOOGLECALENDAR_GET_CURRENT_DATE_TIMEGets the current date and time, allowing for a specific timezone offset.1 params
Gets the current date and time, allowing for a specific timezone offset.
Parameters* required
timezonenumberTimezone offset from UTC in hours. Use positive values for east of UTC, negative for west. Examples: Paris/Berlin: 1 (winter) or 2 (summer), London: 0 (winter) or 1 (summer), New York: -5 (winter) or -4 (summer), Los Angeles: -8 (winter) or -7 (summer), Tokyo: 9, Mumbai: 5.5, Sydney: 10 (winter) or 11 (summer). Default 0 is UTC.
Examples:
0
1
2
-5
-4
-8
-7
-6
3
5.5
8
9
10
11
-3
4
2
-10
-9
5.75
6.5
-3.5default: 0
GOOGLECALENDAR_LIST_ACL_RULESRetrieves the list of access control rules (ACLs) for a specified calendar, providing the necessary 'rule_id' values required for updating specific ACL rules.5 params
Retrieves the list of access control rules (ACLs) for a specified calendar, providing the necessary 'rule_id' values required for updating specific ACL rules.
Parameters* required
page_tokenstringToken specifying which result page to return. Optional.
Example: " nextPageToken_value"
sync_tokenstringToken obtained from the nextSyncToken field returned on the last page of a previous list operation. It makes the result of this list operation contain only entries that have changed since then. Optional. The default is to retrieve all entries.
Example: "nextSyncToken_value"
calendar_idstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "primary"
max_resultsvalueMaximum number of entries returned on one result page. Optional. The default is 100.
Example: 10
show_deletedbooleanWhether to include deleted ACLs in the result. Optional. The default is False.
Example: false
GOOGLECALENDAR_LIST_CALENDARSRetrieves a paginated list of calendars from the user's calendar list, with optional filtering and sync capabilities.6 params
Retrieves a paginated list of calendars from the user's calendar list, with optional filtering and sync capabilities.
Parameters* required
pageTokenstringToken for retrieving a specific page of results from a previous list operation.
syncTokenstringSync token from a previous list request's 'nextSyncToken' to retrieve only entries changed since the last sync. When provided, only 'syncToken' and optionally 'pageToken' are used; other filters are ignored. 'minAccessRole' cannot be combined with 'syncToken'.
maxResultsintegerMaximum number of calendars to return per page. Maximum allowed value is 250.default: 100
showHiddenbooleanInclude calendars hidden in the user interface. When using 'syncToken', hidden (and deleted) entries changed since the previous list are always included, and this parameter must not be set to false.default: false
showDeletedbooleanInclude calendar list entries deleted from the user's list. Deleted entries are returned with the 'deleted' field set to true. When using 'syncToken', deleted (and hidden) entries changed since the previous list are always included, and this parameter must not be set to false.default: false
minAccessRolevalueMinimum access role the user must have for the returned calendars.
Examples:
"freeBusyReader"
"owner"
"reader"
"writer"
GOOGLECALENDAR_PATCH_CALENDARPartially updates (PATCHes) an existing Google Calendar, modifying only the fields provided; `summary` is mandatory and cannot be an empty string, and an empty string for `description` or `location` clears them.5 params
Partially updates (PATCHes) an existing Google Calendar, modifying only the fields provided; `summary` is mandatory and cannot be an empty string, and an empty string for `description` or `location` clears them.
Parameters* required
summarystringNew title for the calendar; cannot be an empty string.
Examples:
"Team Meetings"
"Project Alpha Milestones"
locationstringNew geographic location of the calendar (e.g., 'Paris, France').
Examples:
"Paris, France"
"London"
timezonestringNew IANA Time Zone Database name for the calendar (e.g., 'Europe/Zurich', 'America/New_York').
Examples:
"Europe/Zurich"
"America/New_York"
"Asia/Tokyo"
calendar_idstringIdentifier of the Google Calendar to update; use 'primary' for the main calendar or a specific ID.
Examples:
"primary"
"secondaryCalendarIdAbc..."
"example@group.calendar.google.com"
descriptionstringNew description for the calendar.
GOOGLECALENDAR_PATCH_EVENTUpdate specified fields of an existing event in a Google Calendar using patch semantics (array fields like `attendees` are fully replaced if provided); ensure the `calendar_id` and `event_id` are valid and the user has write access to the calendar.14 params
Update specified fields of an existing event in a Google Calendar using patch semantics (array fields like `attendees` are fully replaced if provided); ensure the `calendar_id` and `event_id` are valid and the user has write access to the calendar.
Parameters* required
summarystringNew title for the event.
Example: "Updated Team Meeting"
end_timestringNew end time (RFC3339 timestamp, e.g., '2024-07-01T11:00:00-07:00'). Uses `timezone` if provided, otherwise UTC. For all-day events, use YYYY-MM-DD format (exclusive end date).
Examples:
"2024-07-01T11:00:00-07:00"
"2024-07-02"
event_idstringIdentifier of the event to update. Must be provided in snake_case format.
Example: "abc123xyz"
locationstringNew geographic location (physical address or virtual meeting link).
Examples:
"Conference Room B"
"https://hangouts.google.com/foo"
timezonestringIANA Time Zone Database name for start/end times (e.g., 'America/Los_Angeles'). Used if `start_time` and `end_time` are provided and not all-day dates; defaults to UTC if unset.
Examples:
"America/Los_Angeles"
"Europe/Berlin"
attendeesvalueList of email addresses for attendees. Replaces existing attendees. Provide an empty list to remove all.
Examples:
["user1@example.com","user2@example.com"]
[]
start_timestringNew start time (RFC3339 timestamp, e.g., '2024-07-01T10:00:00-07:00'). Uses `timezone` if provided, otherwise UTC. For all-day events, use YYYY-MM-DD format.
Examples:
"2024-07-01T10:00:00-07:00"
"2024-07-01"
calendar_idstringIdentifier of the calendar. Use 'primary' for the primary calendar of the logged-in user. To find other calendar IDs, use the `calendarList.list` method. Must be provided in snake_case format.
Examples:
"primary"
"secondary_calendar_id"
descriptionstringNew description for the event; can include HTML.
Example: "Weekly team sync meeting to discuss project updates."
send_updatesstringWhether to send update notifications to attendees: 'all', 'externalOnly', or 'none'. Uses default user behavior if unspecified.
Examples:
"all"
"externalOnly"
"none"
max_attendeesvalueMaximum attendees in response; does not affect invited count. If more, response includes organizer only. Must be positive.
Examples:
10
100
rsvp_responsestringRSVP response status for the authenticated user. Updates only the current user's response status without affecting other attendees. Possible values: 'needsAction', 'declined', 'tentative', 'accepted'.
Examples:
"accepted"
"declined"
"tentative"
"needsAction"
supports_attachmentsbooleanClient application supports event attachments. Set to `True` if so.
Examples:
true
false
conference_data_versionvalueAPI client's conference data support version. Set to 1 to manage conference details (e.g., Google Meet links); 0 (default) ignores conference data.
Examples:
0
1
GOOGLECALENDAR_QUICK_ADDParses natural language text to quickly create a basic Google Calendar event with its title, date, and time, suitable for simple scheduling; does not support direct attendee addition or recurring events, and `calendar_id` must be valid if not 'primary'.3 params
Parses natural language text to quickly create a basic Google Calendar event with its title, date, and time, suitable for simple scheduling; does not support direct attendee addition or recurring events, and `calendar_id` must be valid if not 'primary'.
Parameters* required
textstringNatural language input describing the event; Google Calendar parses this for event details like title, date, and time.
Examples:
"Appointment at Somewhere on June 3rd 10am-10:25am"
"Dentist appointment tomorrow at 2pm for 45 minutes"default:
calendar_idstringIdentifier of the calendar for the event. Use 'primary' for the main calendar, or provide a specific calendar ID (e.g., email address).
Examples:
"primary"
"user@example.com"
"xxxxxxxxxxxxxxxxx@group.calendar.google.com"default: primary
send_updatesstringControls whether email notifications about the event creation are sent to attendees.one of
all · externalOnly · nonedefault: noneGOOGLECALENDAR_REMOVE_ATTENDEERemoves an attendee from a specified event in a Google Calendar; the calendar and event must exist.3 params
Removes an attendee from a specified event in a Google Calendar; the calendar and event must exist.
Parameters* required
event_idstringUnique identifier of the event.
calendar_idstringIdentifier of the Google Calendar to which the event belongs; 'primary' signifies the user's main calendar.default: primary
attendee_emailstringEmail address of the attendee to remove. Must match an attendee email present on the event.
Example: "john@gmail.com"
GOOGLECALENDAR_SETTINGS_LISTReturns all user settings for the authenticated user.3 params
Returns all user settings for the authenticated user.
Parameters* required
pageTokenstringToken specifying which result page to return.
syncTokenstringToken obtained from the nextSyncToken field returned on the last page of results from the previous list request. It makes the result of this list request contain only entries that have changed since then. If the syncToken expires, the server will respond with a 410 GONE response code and the client should clear its storage and perform a full synchronization without any syncToken.
maxResultsvalueMaximum number of entries returned on one result page. By default the value is 100 entries. The page size can never be larger than 250 entries.
GOOGLECALENDAR_SETTINGS_WATCHWatch for changes to Settings resources.5 params
Watch for changes to Settings resources.
Parameters* required
idstringA UUID or similar unique string that identifies this channel.
Example: "channel-ID-1"
typestringThe type of delivery mechanism used for this channel. Valid values are "web_hook" (or "webhook").
Example: "web_hook"
tokenstringAn arbitrary string delivered to the target address with each notification delivered over this channel.
Example: "token-string"
paramsvalueAdditional parameters controlling delivery channel behavior.
addressstringThe address where notifications are delivered for this channel.
Example: "https://example.com/notifications"
GOOGLECALENDAR_SYNC_EVENTSSynchronizes Google Calendar events, performing a full sync if no `sync_token` is provided or if a 410 GONE error (due to an expired token) necessitates it, otherwise performs an incremental sync for events changed since the `sync_token` was issued.6 params
Synchronizes Google Calendar events, performing a full sync if no `sync_token` is provided or if a 410 GONE error (due to an expired token) necessitates it, otherwise performs an incremental sync for events changed since the `sync_token` was issued.
Parameters* required
pageTokenstringToken for paginating results, from a previous response's `nextPageToken`.
Example: "RANDOM_PAGE_TOKEN_STRING"
sync_tokenstringToken for incremental sync, retrieving only changes since issued. A 410 GONE response indicates an expired token, requiring a full sync.
Example: "RANDOM_SYNC_TOKEN_STRING_FROM_PREVIOUS_CALL"
calendar_idstringGoogle Calendar identifier; 'primary' refers to the authenticated user's main calendar.
Examples:
"primary"
"your.email@example.com"
"xxxxxxxxxx@group.calendar.google.com"default: primary
event_typesvalueFilters events by specified types (e.g., 'default', 'focusTime', 'outOfOffice', 'workingLocation'). All types returned if omitted.
Examples:
"['default', 'focusTime']"
"['outOfOffice']"
"['default']"
max_resultsvalueMax events per page (max 2500); Google Calendar's default is used if unspecified.
Examples:
"100"
"2500"
single_eventsbooleanIf True, expands recurring events into individual instances (excluding master event); otherwise, Google's default handling applies.
Examples:
true
false
GOOGLECALENDAR_UPDATE_ACL_RULEUpdates an access control rule for the specified calendar.4 params
Updates an access control rule for the specified calendar.
Parameters* required
rolestringThe role assigned to the scope. Possible values are:
- "none" - Provides no access.
- "freeBusyReader" - Provides read access to free/busy information.
- "reader" - Provides read access to the calendar. Private events will appear to users with reader access, but event details will be hidden.
- "writer" - Provides read and write access to the calendar. Private events will appear to users with writer access, and event details will be visible.
- "owner" - Provides ownership of the calendar. This role has all of the permissions of the writer role with the additional ability to see and manipulate ACLs.
Example: "reader"
rule_idstringACL rule identifier.
Example: "user:test.user@example.com"
calendar_idstringCalendar identifier. To retrieve calendar IDs call the calendarList.list method. If you want to access the primary calendar of the currently logged in user, use the "primary" keyword.
Example: "primary"
send_notificationsbooleanWhether to send notifications about the calendar sharing change. Note that there are no notifications on access removal. Optional. The default is True.default: true
GOOGLECALENDAR_UPDATE_EVENTUpdates an existing event by `event_id` in a Google Calendar; this is a full PUT replacement, so provide all desired fields as unspecified ones may be cleared or reset.23 params
Updates an existing event by `event_id` in a Google Calendar; this is a full PUT replacement, so provide all desired fields as unspecified ones may be cleared or reset.
Parameters* required
summarystringSummary (title) of the event.
event_idstringThe unique identifier of the event to be updated.
Example: "a1b2c3d4e5f6g7h8i9j0k1l2m3"
locationstringGeographic location of the event as free-form text.
timezonestringIANA timezone name (e.g., 'America/New_York'). Required if datetime is naive. For recurring events, start and end must include a timeZone. If not provided, UTC is used. If datetime includes timezone info (Z or offset), this field is optional and defaults to UTC.
attendeesvalueList of attendee emails (strings).
eventTypestringType of the event, immutable post-creation. 'workingLocation' (REQUIRES Google Workspace Enterprise). Note: 'fromGmail' events cannot be created via API.one of
birthday · default · focusTime · outOfOffice · workingLocationdefault: defaultrecurrencevalueList of RRULE, EXRULE, RDATE, EXDATE lines for recurring events. Supported frequencies: DAILY, WEEKLY, MONTHLY, YEARLY. For recurring events, start.timeZone and end.timeZone must be present. Provide an empty list to remove recurrence so the event becomes non-recurring.
visibilitystringEvent visibility: 'default', 'public', 'private', or 'confidential'.one of
default · public · private · confidentialdefault: defaultcalendar_idstringIdentifier of the Google Calendar where the event resides. The value 'primary' targets the user's primary calendar.
Examples:
"primary"
"user@example.com"
"long_calendar_id@group.calendar.google.com"default: primary
descriptionstringDescription of the event. Can contain HTML. Optional. Must be omitted for 'birthday' event type.
send_updatesbooleanDefaults to True. Whether to send updates to the attendees.
transparencystring'opaque' (busy) or 'transparent' (available).one of
opaque · transparentdefault: opaquestart_datetimestringEvent start time in format YYYY-MM-DDTHH:MM:SS (no fractional seconds, no 'Z', no timezone offsets). Examples: '2025-01-16T13:00:00' or '2025-01-16T13:00'. Timezone info (Z, +, -) will be automatically stripped if provided.
guests_can_modifybooleanIf True, guests can modify the event.default: false
birthdayPropertiesvalueProperties for birthday events.
create_meeting_roombooleanIf true, a Google Meet link is created and added to the event. CRITICAL: As of 2024, this REQUIRES a paid Google Workspace account ($13+/month). Personal Gmail accounts will fail with 'Invalid conference type value' error. Solutions: 1) Upgrade to Workspace, 2) Use domain-wide delegation with Workspace user, 3) Use the new Google Meet REST API, or 4) Create events without conferences. See https://github.com/googleapis/google-api-nodejs-client/issues/3234
event_duration_hourintegerNumber of hours (0-24). Increase by 1 here rather than passing 60 in `event_duration_minutes`default: 0
focusTimePropertiesvalueProperties for focusTime events. REQUIRES Google Workspace Enterprise account with Focus Time feature enabled.
guestsCanInviteOthersbooleanWhether attendees other than the organizer can invite others to the event.
outOfOfficePropertiesvalueProperties for outOfOffice events.
event_duration_minutesintegerDuration in minutes (0-59 ONLY). NEVER use 60+ minutes - use event_duration_hour=1 instead. Maximum value is 59. Combined duration (hours + minutes) must be greater than 0.default: 30
guestsCanSeeOtherGuestsbooleanWhether attendees other than the organizer can see who the event's attendees are.
workingLocationPropertiesvalueProperties for workingLocation events. REQUIRES Google Workspace Enterprise.
Constraints discovered from testing:
- Must set transparency='transparent' and visibility='public'
- Description must be omitted
- Depending on 'type', include one of 'homeOffice', 'officeLocation', or 'customLocation'
google-cal-mcp
MCP server for Google Calendar - list, create, update, and manage calendar events.
Use Cases
Schedule meetings: "Set up a 30-min sync with Sarah next week" → finds a free slot, creates the event with a Meet link, and sends the invite.
RSVP to invites: "Accept the team offsite but decline the vendor demo" → responds to pending invitations automatically.
Find availability: "When am I free this Thursday afternoon?" → queries your calendar and returns open slots.
Reschedule events: "Move my 1:1 with Alex to Friday at 2pm" → updates the event and notifies attendees.
Daily briefing: "What's on my calendar today?" → lists all events with times, locations, and attendees.
Block focus time: "Block 2 hours tomorrow morning for deep work" → creates a calendar event to protect your time.
(These are just examples - any workflow that needs calendar access can use this.)
Setup
1. Create Google OAuth credentials
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable the Google Calendar API
- Go to APIs & Services → OAuth consent screen, set up consent screen
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Choose Web application
- Add
http://localhost:3000/callbackto Authorized redirect URIs - Note your Client ID and Client Secret
2. Run the server
GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start
The server runs on http://localhost:3000 by default. Change with PORT=3001.
3. Add to your MCP client
claude mcp add --transport http google-cal-mcp http://localhost:3000/mcp
Architecture
This server acts as an OAuth proxy to Google:
graph LR
A[MCP client] <--> B[google-cal-mcp] <--> C[Google OAuth/API]
- Server advertises itself as an OAuth authorization server via
/.well-known/oauth-authorization-server /registerreturns the Google OAuth client credentials/authorizeredirects to Google, encoding the client's callback URL in state/callbackreceives the code from Google and forwards to the client's callback/tokenproxies token requests to Google, injecting client credentials/mcphandles MCP requests, using the bearer token to call Calendar API
The server holds no tokens or state - it just proxies OAuth to Google.
Tools
| Tool | Description |
|---|---|
| Calendars | |
calendars_list | List all calendars the user has access to |
calendarlist_insert | Subscribe to a shared calendar |
calendarlist_update | Update calendar settings (color, visibility, reminders) |
calendarlist_delete | Unsubscribe from a calendar |
| Events | |
events_list | List events in a time range with search/filter |
event_get | Get details of a specific event |
event_create | Create a new event with attendees and Meet link |
event_update | Update an existing event |
event_delete | Delete an event |
event_respond | RSVP to an invitation (accept/decline/tentative) |
event_move | Move event to a different calendar |
event_instances | Get instances of a recurring event |
| Availability | |
freebusy_query | Find free/busy times for scheduling |
| Sharing | |
acl_list | List who has access to a calendar |
| Colors | |
colors_get | Get available color palette for calendars/events |
Calendar API Scopes
calendar- Full access to calendarscalendar.events- Read/write events
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install - Run
npm run testto run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>to bump the version - Run
git push --follow-tagsto push with tags - Wait for GitHub Actions to publish to the NPM registry.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
GOOGLE_ACCESS_TOKEN*secretGoogle OAuth access token with Calendar scopes.
MCP_TRANSPORT*Transport type.
GOOGLE_CLIENT_ID*Google OAuth client ID.
GOOGLE_CLIENT_SECRET*secretGoogle OAuth client secret.
Categories
Registryactive
Packagegoogle-cal-mcp
TransportSTDIO, HTTP
AuthRequired
UpdatedMay 25, 2026
