Google Calendar MCP

google-calendar-mcp

An MCP server for Google Calendar. One binary, stdio, per-user OAuth against your own Google account.

It answers when — calendars, the events on them, and who is free. What a meeting produces (a recording, a notes document, an attachment) belongs to servers built on the Meet, Docs and Drive APIs. get_event names the files attached to an event, with the Drive file id those servers take.

It is for one person who uses Google Calendar, on a Workspace or a personal Google account, and wants an assistant to read and change that calendar as them. You create your own OAuth client in Google Cloud once, and nothing is hosted.

Goals and non-goals

Goals:

• Correct about time. An all-day event stays a date, every timed write carries an IANA zone, and every read states its window and zone.
• Nobody emailed by surprise. notify is required on any write that can reach a guest, and scope on any write to a repeating event, with no default for either.
• A write never overwrites what it did not see. Every change is a patch under the etag of the read that planned it.
• Safe by default. What cannot be taken back, and every share beyond your organization, is registered only when you turn it on. Read-only mode removes every write, and the writes take dry_run.
• Act as you, and log nothing about your calendar. Every call runs as the signed-in account, and the logs never carry event content or addresses.

Non-goals:

• What a meeting produces. Recordings, notes documents and the files attached to an event belong to the Drive and Docs servers. Google Tasks is a separate API.
• Push notifications. Google's watch methods need a public HTTPS endpoint, which a stdio server cannot offer. list_changes hands back a sync token instead.
• A local cache or sync loop. The server keeps no copy of your calendar between calls.
• Migration and administration. Importing events from another system and transferring a calendar's ownership as an administrator are out.
• Parsing natural language into events. Google's quick-add hides which fields it set and in which zone it read the time; the model calling this server parses better.
• A hosted service. It speaks stdio only, so Claude on the web and on mobile cannot reach it.
• Asking you before a call. Your client approves each call; the server asks nothing.

What makes this one different

Calendar tooling often gets these wrong. This server is built around getting them right, and a test enforces each:

• An all-day event is a date, not a time. It never becomes an instant, so it cannot land on the wrong day for anyone west of UTC. Every timed event carries a real IANA zone, not just an offset, because an offset cannot expand a repeating event across a daylight-saving change.
• Every read says what it read. The absolute window, the time zone, where that zone came from, and whether the list was truncated. A schedule that does not say which Thursday it is showing can be read as any Thursday.
• Availability is not a list of events. An event you cannot see the details of still makes someone busy, and an event marked "free" does not. A calendar that could not be read is reported as *unknown*, never folded into "free".

The design and the decisions behind it are in docs/architecture.md.

Install

go install github.com/mmedum/google-calendar-mcp/v5/cmd/google-calendar-mcp@latest

Or take a signed archive from the latest release. docs/release.md gives the commands that verify it.

Set up

You need your own Google Cloud project and OAuth client. Nothing deployer-specific is baked into this repository.

1. Create a project and enable the Google Calendar API.
2. Configure the OAuth consent screen and, on an External app, add the scopes docs/gcp-setup.md lists; an Internal app needs no list. A gate checks that file against the code, so it cannot fall behind what login asks for.
3. Create an OAuth client of type Desktop app and download the JSON.
4. Sign in:

google-calendar-mcp login --client-secret ~/path/to/client_secret.json

google-calendar-mcp doctor

doctor checks the client JSON, the stored token, the granted scopes and whether the API answers, and names what is missing.

Signing in over SSH

The OAuth callback reaches the loopback interface of the machine running login, while your browser is on your own machine. Forward the port first. Use --no-browser: it prints the authorization URL and the exact ssh -L line to run, with the port it actually picked.

Configure your MCP client

{

"mcpServers": { "google-calendar": { "command": "google-calendar-mcp", "env": { "GCAL_CLIENT_SECRET": "/path/to/client_secret.json" } } } }

Every setting is in docs/configuration.md.

Claude Desktop

Every release also carries a .mcpb bundle. Open it and Claude Desktop installs the server and asks for the settings a client's configuration would carry: your OAuth client JSON, which may be left empty to use the one login recorded, the profile, read-only and the switches. Deleting a calendar or every event on one, publishing it and sharing it outside your organization (enable_destructive), and an event that declines every meeting it overlaps (enable_decline_all) stay off unless you turn them on. Sharing inside your organization (sharing) stays on, as on a server you configure by hand, and read-only leaves every switch nothing to register. This server asks nobody before a call. Claude Desktop approves each tool, with Allow once or Always allow, and a tool you always allow then runs unasked, so leave a switch off unless you need its tools.

The bundle covers macOS, Windows and Linux on both architectures: macOS through a universal binary, Windows through amd64, and Linux through a small launcher that picks the binary at start. It does not log you in. Install the binary as well, run google-calendar-mcp login once, and the bundle uses the same login.

Tools

GCAL_READ_ONLY=true registers only the reads, the rows above create_event, and requests only read scopes, so the API itself refuses a write.

manage_calendar covers what the API splits across two resources and people do not: the calendar — its title, description, location and time zone — is what everybody it is shared with sees, while your subscription to it — the color, the name you give it, whether it is hidden, what you are emailed about — is yours alone. Unsubscribing removes it from your list; it deletes nothing and nobody else notices.

These rules run through every write:

• `notify` is required whenever the write can reach another person, and there is no default in either direction. none is refused outright when a guest is outside your organization — such a guest may have no Google Calendar for the event to appear in, so email is the only way they can learn of it.
• `scope` is required when the event repeats: instance, series or this_and_following. "Move the standup to 10:30" is three different operations and the API makes them look like one.
• Every write is a patch under `If-Match`, so it is refused as [stale] rather than overwriting somebody who changed it first. Adding a guest reads the list and adds to it; it never replaces it.

dry_run: true on any of them reports what would change and how many guests would be emailed, without writing.

Above 200 guests Google stops propagating individual responses, so every result about such an event says that the RSVPs it lists are incomplete.

Resources

For clients that attach context rather than call tools, the same content is published as resources:

They carry no handles and take no arguments, which is why there is no resource for a schedule: a window and a zone are not optional here, and a URI with nowhere to state them would have to invent both.

Working hours

check_availability answers over a window, and a window is one interval — so "next week, 09:00 to 17:00" cannot be asked for