Google Calendar MCP

Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.

Takes no parameters.

Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die after 7 days), downloading the client JSON and handing its PATH to set_client. Works without any credentials; the checklist shortens to 'enable the API + log in' when an OAuth client is already configured (one client serves the whole mcp-google-* line). Never asks the user to paste secrets into the chat.

Takes no parameters.

Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.

First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.

Takes no parameters.

Second step: waits up to 20 s for the browser consent to finish, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.

Takes no parameters.

Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.

Takes no parameters.

Lists the calendars on the user's calendar list: id (use it as calendar_id in every other tool), summary, description, timeZone (IANA), accessRole (owner/writer/reader/freeBusyReader — writes need writer or owner), primary:true on the main calendar, and hidden/selected flags. The special id "primary" always addresses the main calendar without listing first. Paginate with page_token from nextPageToken. Calendars shared with the user but never added to their list do not appear here — address them by their explicit id.

Fetches one calendar-list entry: summary, description, timeZone (the calendar's default IANA zone — use it to interpret event times), accessRole, defaultReminders and primary. Works only for calendars on the user's list; for a shared calendar never added to the list, use raw_request with path calendar/v3/calendars/<id> instead.

Lists events on a calendar: id, summary, start/end (all-day events carry date with an EXCLUSIVE end; timed events carry dateTime), status, attendees with responseStatus, organizer, recurrence, hangoutLink, eventType. time_min/time_max bound the window (an event overlapping the window is included). single_events=true expands recurring events into individual instances — required for order_by=start_time and the right choice for questions like "what is on my calendar this week"; without it recurring events appear once as the series master. time_zone only changes how times are RENDERED in the response, never the events themselves. q searches summary/description/location/attendees. updated_min + show_deleted enable incremental polling (cancelled events come back as status=cancelled). Paginate with page_token from nextPageToken.

Fetches one event by id: summary, description, location, start/end, attendees with their responseStatus (accepted/declined/tentative/needsAction), organizer, recurrence rules, recurringEventId (present on instances of a series), conferenceData/hangoutLink (Google Meet), reminders, visibility, transparency and eventType. Works for a series master and for an individual instance id alike.

Creates an event and returns it (id, htmlLink, start/end, attendees, hangoutLink when add_meet). Times: EITHER start_date_time + end_date_time (RFC3339; add time_zone for recurring events) OR start_date + end_date for all-day (end_date is EXCLUSIVE — the day after the last day). recurrence makes it a recurring series. attendees invites guests — but the API sends invitation emails ONLY with send_updates=all (the default notifies nobody). add_meet attaches a Google Meet link (may come back status=pending — re-run get_event for the final URL). This is a plain calendar write: it does not check for conflicts — call query_free_busy first to find a free slot. Never blindly re-send after a timeout or 5xx: the event may already exist — check with list_events first, or you will create a duplicate and re-invite everyone.

Partially updates an event (PATCH): only the provided fields change, but a provided nested object REPLACES its predecessor wholesale — attendees replaces the entire guest list (get_event first, send the complete new list), reminders replaces all overrides, and a time change should carry BOTH the new start and end (start_date_time + end_date_time, or start_date + end_date). To reschedule one occurrence of a recurring series, pass that instance's id (from list_event_instances) as event_id; passing the series master id changes every occurrence. Guests hear about the change only with send_updates=all. Also works to update Out of Office / Focus Time blocks. Returns the updated event.

Deletes (cancels) an event — there is no undelete. Deleting a series master id cancels the ENTIRE recurring series; deleting one instance id (from list_event_instances) cancels only that occurrence. On an event with guests this cancels the meeting for everyone, but cancellation emails go out only with send_updates=all. Returns {deleted:true}.

Moves an event to a different calendar (changes its organizer calendar; the event id stays the same). Rescheduling to another TIME is update_event, not this. Only regular events can move — Out of Office, Focus Time, working-location and birthday events cannot, and events with attendees can be moved only by their organizer. Needs writer access to both calendars. send_updates=all notifies the guests.

Expands one recurring event (the series master id) into its individual instances, each with its own id (like masterId_20260901T100000Z) and concrete start/end. Use an instance id with update_event to reschedule a single occurrence, or with delete_event to cancel just that one; exceptions already made to the series show their changed times here. show_deleted=true includes cancelled occurrences. Bound the window with time_min/time_max — an unbounded infinite series is paginated via page_token.

Returns the busy intervals of up to 50 calendars in one time window — the way to find a common free slot before create_event. Input calendar ids (or attendee email addresses, which double as their primary-calendar ids — subject to their sharing settings). The response maps each calendar id to busy:[{start,end}] ranges; gaps between them are free. Only busy blocks come back — never event titles or details — and events marked transparent (free) don't appear. A calendar the user cannot read shows up under errors, not busy. This is a pure read despite being an HTTP POST.

Creates an Out of Office event that can auto-decline meeting invitations while it lasts (auto_decline: all overlapping meetings, or only new invitations; decline_message customizes the reply). ONLY works on the PRIMARY calendar of a Google Workspace account — consumer Gmail and secondary calendars get HTTP 400. Always timed (start/end date_time), never all-day. Manage it afterwards like any event: update_event to change it, delete_event to remove it, list_events with event_types=["out_of_office"] to find existing blocks. Not retried after an ambiguous failure — check list_events before re-sending.

Creates a Focus Time event: blocks the slot, can auto-decline conflicting invitations (auto_decline + decline_message) and can flip Google Chat to Do Not Disturb (chat_status). ONLY works on the PRIMARY calendar of a Google Workspace account — consumer Gmail and secondary calendars get HTTP 400. Always timed (start/end date_time), never all-day. Manage it afterwards like any event: update_event / delete_event, and list_events with event_types=["focus_time"] to find existing blocks. Not retried after an ambiguous failure — check list_events before re-sending.

Escape hatch to call any Google Calendar API v3 path directly, for requests the typed tools don't cover — e.g. events.quickAdd ("calendar/v3/calendars/primary/events/quickAdd?text=Lunch tomorrow noon", POST), the colors palette ("calendar/v3/colors"), ACL rules, secondary-calendar creation ("calendar/v3/calendars", POST), removing a Meet conference (PATCH with {"conferenceData":null} and ?conferenceDataVersion=1), watch channels, or an event PUT that replaces every field. The path is relative to https://www.googleapis.com, must stay under calendar/v3/ (other Google APIs on this host — drive/v3, gmail/v1, ... — are rejected before any request is sent) and may carry a query string. The Bearer token is added automatically; the method defaults to GET. Remember: PUT replaces unspecified fields with defaults — prefer PATCH semantics via update_event when possible.