io.github.mmedum/google-calendar-mcp

Cancel an event, or one occurrence of a repeating one. A whole event is deleted; one occurrence is marked canceled, which is how a single date leaves a series — the result says which of the two happened. Google keeps the record either way, and list_events with show_canceled still shows it. `scope` is REQUIRED when the event repeats, and there is no default because the same words mean three different things: `instance` changes one occurrence, `series` changes all of them, and `this_and_following` changes this occurrence and every later one. Name the occurrence with the occurrence's own id, or with the series id plus `original_start` — the scheduled start, which list_instances reports, and which still identifies an occurrence somebody has moved. With `this_and_following` the series simply ends before this occurrence, which is one call rather than the two an update takes. `notify` is REQUIRED whenever the write can reach another person, and this server has no default in either direction: `none` asks Google to email nobody, `external_only` emails the guests outside your own organization, `all` emails every guest. `none` is refused outright when a guest is outside your organization, because such a guest may have no Google Calendar for the event to appear in and email is then the only way they can learn of it. Whatever you pass, the result says what was ASKED FOR — Google reports nothing about what arrived, and `none` is not a promise of silence. Read that rule twice here: canceling with no notification removes the meeting from YOUR calendar and leaves it on your guests'. They will still turn up. Every write is a patch under If-Match, so it is refused as `[stale]` rather than overwriting somebody who changed this first. Pass `etag` from the get_event you decided on to be held to that exact version; pass `force: true` only when you genuinely mean "whatever it says now". Without `etag`, a write refused that way is read again and made once more if nothing it changes, reache…

When people are busy, and when they are free, in a window. `from` and `to` are required and take either a yyyy-mm-dd date or an RFC3339 timestamp. A bare date means that whole day in the resolved zone, so from and to on the same date is that one day. Resolve relative expressions like "next Tuesday" yourself before calling: this server does not guess, and the result always echoes the absolute window and the zone it used so you can check the resolution. Times are shown in `time_zone` if you pass one, otherwise the calendar's own zone, otherwise the zone in the account's Calendar settings. The result names which of the three it used. This server never falls back to the machine's own clock zone. This asks Google's free/busy service rather than listing events, which matters: it sees busy time on calendars whose events you cannot read, and it respects events marked "free", so a list of events is not the same answer. A calendar that could not be read comes back as UNKNOWN, never as free — do not book over it. A group's address is answered for its members together, and is unknown if any of them is. The result also reports the gaps when nobody is busy; min_minutes drops the ones too short to use. working_from, working_to and working_days mask the gaps to a working week: a window is one interval, so "next week, 09:00 to 17:00" cannot be asked for as a window and would otherwise come back with a fifteen-hour gap every night. There is no default — without them every hour of the window counts, and the result always says which was used. Calendars are asked in batches of 50, and the result says how many requests that took.

Create a new calendar of your own. You are its owner, it appears in your calendar list, and nobody else can see it until you share it — use share_calendar for that. It is created in `time_zone` if you pass one, otherwise the zone in this account's Calendar settings; the result says which it used, and every time written to the calendar afterward is read against it. Creating a calendar is quota-counted by Google and deleting one does not give the quota back, so do not create one per task. `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have.

Create an event. `start` and `end` are either two yyyy-mm-dd dates for an all-day event, where `end` is the LAST day and is included, or two RFC3339 timestamps for a timed one — never one of each, because a date is not a time. Times are written in `time_zone` if you pass one, otherwise the calendar's own zone; the result says which it used, and the zone is always sent alongside the timestamp so a repeating event keeps its wall-clock time across a daylight-saving change. `recurrence` takes RFC 5545 lines such as RRULE:FREQ=WEEKLY;BYDAY=TU;COUNT=10. `conference: true` asks Google for a Meet link. The link normally comes back with the event, but Google may still be making it — the result says which, and when it says the link is still being made, read the event again to get it rather than promising anybody a link. update_event's `add_conference` adds one to an event later. `optional_guests` invites people as optional; they are emailed like any guest, so they make notify required too. A room cannot be optional. An address may be bare or a mailbox such as "Sample Person" <person@example.com>, the way a mail server hands one over; only the address is used, and one entry holds one address. `popup_reminders` and `email_reminders` are minutes before the start, 0 to 40320, at most five in all. Either one replaces the whole set, so pass both to keep both kinds, and an empty list given alone means no reminders. `default_reminders: true` goes back to the calendar's own. Reminders are yours alone: Google keeps them per person, so they never notify a guest. `visibility` is default, public or private: private shows the details only to the guests, and public to everybody who can see the calendar. `guests_can_modify`, `guests_can_invite_others` and `guests_can_see_other_guests` say what a guest may do. `event_type` makes a status event, which only your primary calendar can hold: outOfOffice, focusTime or workingLocation. Out of office and focus time are timed, never all day, and alwa…

One calendar in full: its description, time zone, your access level, and who else it is shared with. Use list_calendars to see every calendar; use this when you need the sharing list or are checking whether you may write somewhere.

One event in full, including its guests and their responses, its recurrence rule if it has one, and its etag. Times are shown in `time_zone` if you pass one, otherwise the calendar's own zone, otherwise the zone in the account's Calendar settings. The result names which of the three it used. This server never falls back to the machine's own clock zone. It lists the files attached to the event with each one's Drive file id; this server never opens a file, so pass the id to a Drive server to read one. An event id is unique per calendar and not globally, so `calendar` is required alongside it. Ids come from list_events or search_events.

The account's own Calendar settings: its time zone, which day the week starts on, and the color palette. The time zone here is the last fallback for every other tool, so read it when you need to know what "today" or "9am" means for this person.

List the calendars this account can see, with each one's id, time zone and your access level. Start here: every other tool takes a calendar, the ids come from this list, and the time zone it reports is what dates and times elsewhere are read against. It is cheap. Use get_calendar for one calendar's description and who it is shared with.

What changed on a calendar since you last looked. This is the only read that reports DELETIONS: a deleted event stops matching a window, so list_events cannot tell you it is gone, and this returns its id under deleted. Call it once with no sync_token to get a baseline and a token; pass that token next time and you get only what has changed since. The token comes back with the LAST page only. A baseline therefore pages all the way to the end to fetch one, and says how many rows it passed over on the way — they are covered by the token, not lost. An INCREMENTAL read stops at its budget instead and hands back no token, because every row there is a change you have not seen yet; continue with page_token and the same sync_token until the token arrives, and never store one you did not get. It takes no window, no search and no ordering: Google forbids all of them alongside a sync token, and deleted events are always included. If the token has expired the call fails [stale]; ask again with no sync_token and start over. updated_since asks instead for what changed since a moment, such as "since Monday": an RFC3339 time, or a yyyy-mm-dd date meaning the start of that day in time_zone, else the calendar's zone; the result echoes the instant it used. It cannot be combined with sync_token. Events deleted since then are always included. Google calls this the legacy way and says it can miss updates: an event whose only change was its reminders is not reported. Its last page hands back a sync token too, to follow the calendar from there; continue a read that stopped early with page_token and the same updated_since. A moment too far back fails [stale]; pass a later one.

Read a schedule: the events on one or more calendars in a window. `from` and `to` are required and take either a yyyy-mm-dd date or an RFC3339 timestamp. A bare date means that whole day in the resolved zone, so from and to on the same date is that one day. Resolve relative expressions like "next Tuesday" yourself before calling: this server does not guess, and the result always echoes the absolute window and the zone it used so you can check the resolution. Times are shown in `time_zone` if you pass one, otherwise the calendar's own zone, otherwise the zone in the account's Calendar settings. The result names which of the three it used. This server never falls back to the machine's own clock zone. `expand` decides which shape you get, and the two are genuinely different: with expand=true (the default) a repeating event appears as each of its occurrences, which is what you want to answer "what is on this week". With expand=false it appears once, as a series with its recurrence rule, which is what you want before changing the whole series. Canceled events are hidden unless show_canceled is set. event_types keeps only some kinds of event, such as outOfOffice, and the result names the filter. ical_uid keeps only the event with that iCalendar UID, which is how to find the event an invitation email is about. Every occurrence of a repeating event shares one UID, so with expand you get each occurrence in the window. The window still applies: make it wide enough for a meeting that may have moved. Use search_events to find an event by text; use check_availability to find free time, because a list of events is not the same as being free.

The occurrences of one repeating event. `event_id` is the SERIES id, which list_events reports as series_id on each occurrence — an occurrence's own id is not a series id. Pass both from and to for a window, or neither for the whole series. Times are shown in `time_zone` if you pass one, otherwise the calendar's own zone, otherwise the zone in the account's Calendar settings. The result names which of the three it used. This server never falls back to the machine's own clock zone. Each occurrence reports its own id, and says when it was moved from its scheduled time. Canceled occurrences are hidden unless show_canceled is set, and a canceled occurrence is how one date is removed from a series — so pass it when you need to know which dates are gone. Use get_event on the series id to see the recurrence rule itself.

Who can see a calendar, and what each of them can see. Roles are explained rather than echoed, because `writerWithoutPrivateAccess` and `freeBusyReader` do not say what they mean. A rule reading ANYONE means the calendar is public to the whole internet. Reading this needs the calendar.acls.readonly scope, which calendar.readonly does not cover: if it was not granted the call says so rather than reporting an empty list, because "could not read" and "shared with nobody" are different answers.

Change a calendar, or change how you see it, or add and remove it from your list. A calendar is two things and the difference is visible to other people: the CALENDAR itself — its title, description, location and time zone — is what everybody it is shared with sees, and YOUR SUBSCRIPTION to it — the color, the name you give it, whether it is hidden, what you are emailed about — is yours alone. Renaming the calendar renames it for the team; `my_name` renames it only for you. `subscribe` adds an existing calendar to your list by id; `unsubscribe` removes it from YOUR list and does not delete it, does not touch its events and changes nothing for anybody else. Use delete_calendar to remove a calendar itself. `notifications` replaces the whole list of what you are emailed about on this calendar; an empty list turns them all off. Email is the only delivery Google offers. Only the fields you pass are touched. There is no `etag` here on purpose: the two halves are two resources with two etags, so each patch is made under the etag of the read this call just did, and the result shows before and after for every field it changed. `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have.

Move an event to another calendar, which changes who organizes it. The event keeps its id but is addressed on the new calendar from then on. This does NOT change the time — use update_event for that. `scope` is REQUIRED when the event repeats, and there is no default because the same words mean three different things: `instance` changes one occurrence, `series` changes all of them, and `this_and_following` changes this occurrence and every later one. Name the occurrence with the occurrence's own id, or with the series id plus `original_start` — the scheduled start, which list_instances reports, and which still identifies an occurrence somebody has moved. `this_and_following` is not available here: there is nothing to split when the event is simply changing calendars. `notify` is REQUIRED whenever the write can reach another person, and this server has no default in either direction: `none` asks Google to email nobody, `external_only` emails the guests outside your own organization, `all` emails every guest. `none` is refused outright when a guest is outside your organization, because such a guest may have no Google Calendar for the event to appear in and email is then the only way they can learn of it. Whatever you pass, the result says what was ASKED FOR — Google reports nothing about what arrived, and `none` is not a promise of silence. Every write is a patch under If-Match, so it is refused as `[stale]` rather than overwriting somebody who changed this first. Pass `etag` from the get_event you decided on to be held to that exact version; pass `force: true` only when you genuinely mean "whatever it says now". Without `etag`, a write refused that way is read again and made once more if nothing it changes, reaches or asked about has changed, and the result says so. `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have.

Answer an invitation: accepted, declined or tentative, with an optional comment. This changes only THIS account's response and nothing else on the event — which is why it is a separate tool rather than an update. Do not RSVP by patching the guest list; that overwrites everybody else's answer. `scope` is REQUIRED when the event repeats, and there is no default because the same words mean three different things: `instance` changes one occurrence, `series` changes all of them, and `this_and_following` changes this occurrence and every later one. Name the occurrence with the occurrence's own id, or with the series id plus `original_start` — the scheduled start, which list_instances reports, and which still identifies an occurrence somebody has moved. `this_and_following` is not available here: answering some occurrences and not others would mean rewriting somebody else's series. `notify` is REQUIRED whenever the write can reach another person, and this server has no default in either direction: `none` asks Google to email nobody, `external_only` emails the guests outside your own organization, `all` emails every guest. `none` is refused outright when a guest is outside your organization, because such a guest may have no Google Calendar for the event to appear in and email is then the only way they can learn of it. Whatever you pass, the result says what was ASKED FOR — Google reports nothing about what arrived, and `none` is not a promise of silence. `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have.

Find events matching free text in a window. `from` and `to` are required and take either a yyyy-mm-dd date or an RFC3339 timestamp. A bare date means that whole day in the resolved zone, so from and to on the same date is that one day. Resolve relative expressions like "next Tuesday" yourself before calling: this server does not guess, and the result always echoes the absolute window and the zone it used so you can check the resolution. Google documents the fields the text is matched against: the title, description and location, the guests' and organizer's names and addresses, and a working location's labels; words such as "Out of office" also match those kinds of event, in any language. There is no field syntax: you cannot search "attendee:someone" or restrict it to titles. How words are matched is not documented, and an event you can see only as busy has nothing to match, so treat an empty result as "this search found nothing", not as "there is no such event", and fall back to list_events over the window when you need certainty. event_types narrows the search to some kinds of event, as on list_events. Searching several calendars costs one request each.

Give somebody access to a calendar, or change the access they already have. `who` is an email address, a group address, a domain, or "anyone" for the public internet. An address is read as one person unless this calendar already has a rule for it — pass `scope_type` to be sure, because a group address and a person's look identical. `role` is what they may do: freeBusyReader, reader, writerWithoutPrivateAccess, writer or owner. The result explains the one it set. Sharing with "anyone" publishes the calendar to the whole internet and needs `allow_public: true`: removing the rule later stops new readers and takes nothing back from whoever already looked. `notify` is REQUIRED and has no default: `all` asks Google to email about the change, `none` asks it not to. Google's own default here is to EMAIL — the opposite of its default on an event — which is why this server asks rather than inheriting either. `external_only` has no meaning on a sharing change and is refused: Google's switch is on or off, with no internal/external split. Whatever you pass, the result says what was ASKED FOR; the API reports nothing about what arrived. The result lists who could see the calendar before and who can see it now, because "shared with somebody" is not an answer to "who can see this". `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have. When the client can, the server also asks the person before a share that publishes the calendar, opens it to a whole domain, or makes somebody an owner; a call they do not confirm is [blocked], and is not made again unless they ask.

Take somebody's access to a calendar away. `who` is the address, domain or "anyone" whose rule should go; the server finds the rule itself, and says so if there is none. There is no notify here, and that is Google's shape rather than an omission: nobody is emailed when access is removed and there is no way to ask for it. They are not told — they find the calendar gone. Removing the public rule stops new readers and takes nothing back from anybody who already looked. The result lists who could see the calendar before and who can see it now, because "shared with somebody" is not an answer to "who can see this". `dry_run: true` reports exactly what would change and how many guests would be emailed, without writing anything. Use it when you are not certain which event or which occurrence you have.

Change an event. Only the fields you pass are touched; everything else is left exactly as it is, so this can never drop a guest list or flatten a series the way a whole-resource write does. Guests are added and removed one at a time with `add_guests` and `remove_guests`, optional guests added with `add_optional_guests`, and rooms booked with `add_rooms`, applied to the list as it is read, so somebody else's RSVP arriving in between is reported rather than overwritten. An address already on the event keeps the role it has, and the result names it: this server does not make a guest optional or required, and a call that would add nothing else is refused as having nothing to change. An address may be bare or a mailbox such as "Sample Person" <person@example.com>, the way a mail server hands one over; only the address is used, and one entry holds one address. `scope` is REQUIRED when the event repeats, and there is no default because the same words mean three different things: `instance` changes one occurrence, `series` changes all of them, and `this_and_following` changes this occurrence and every later one. Name the occurrence with the occurrence's own id, or with the series id plus `original_start` — the scheduled start, which list_instances reports, and which still identifies an occurrence somebody has moved. `this_and_following` is two calls: the original series is ended before this occurrence and a NEW series starts at it with a new id, and any exception after this occurrence is reset. The result says so. `popup_reminders` and `email_reminders` are minutes before the start, 0 to 40320, at most five in all. Either one replaces the whole set, so pass both to keep both kinds, and an empty list given alone means no reminders. `default_reminders: true` goes back to the calendar's own. Reminders are yours alone: Google keeps them per person, so they never notify a guest. A write that changes only reminders needs no `notify`, except with `this_and_following`, whose new s…