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.

What makes this one different

Most calendar tooling an LLM reaches for gets three things subtly wrong. This server is built around not getting them wrong, and each is enforced by a test rather than by care:

• 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, its evidence log and the phase plan are in docs/architecture.md.

Related MCP server: Google-Calendar Universal MCP

Status

Complete and in use: reading, writing, recurrence, availability, calendars, sharing, the resources and the Claude Desktop bundle. The tools are listed below, and the phase plan and what is still owed are in docs/architecture.md §16.

Install

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

Or download an archive from the releases page.

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 add the scopes docs/gcp-setup.md lists. That file is generated from the code, so it cannot fall behind the tool surface.

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 three 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 the first nine 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.

Three rules run through every write, and each exists because guessing is what the surveyed servers do:

• 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 three 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 as one, and the longest gap in the answer is a fifteen-hour overnight one that passes any min_minutes. working_from, working_to and working_days mask the free gaps to a working week instead. There is no default: without them every hour of the window counts, and the result always says which was used. The mask is applied in the zone the answer is rendered in, day by local day, so 09:00 is still 09:00 on the Sunday the clocks change.

Meeting links

create_event takes conference: true and asks Google for a Google Meet link. The link normally comes back with the event; Google documents the conference as generated asynchronously, so the result may instead say it is still being made, and then you read the event again for it. Either way the result says which, and never reports a link it does not have. update_event takes add_conference to add one to an event that has none.

Safety

• The two tools that remove something Calendar cannot bring back — delete_calendar and clear_calendar — and the two that widen who can see a calendar — publish_calendar and widen_calendar_access — are not registered at all unless GCAL_ENABLE_DESTRUCTIVE=true, and each still needs confirm: true on the call. The two shares also take the calendar's title as list_calendars shows it, so the call names the calendar it opens. cancel_event is deliberately not behind that flag: canceling a meeting is what a calendar is for, Google keeps the record, and a gate everybody turns on protects nobody. docs/architecture.md §9 argues it. What guards it instead is the required scope and the required notify.

• A cancellation with notify: none removes the meeting from your calendar and leaves it on your guests'. The result says so every time.

• Sharing is the one act here whose effect leaves your account, so every sharing tool requires notify like every other write — and here Google's own default is to email, the opposite of its default on an event. share_calendar takes named people and groups inside your organization, below owner: an address is inside when its domain is your account's own, and a personal Google account has no organization, so every address is outside it. Publishing to "anyone" or a whole domain is publish_calendar, and sharing outside or making an owner is widen_calendar_access; share_calendar still lowers the access of anybody the calendar is already shared with. Removing a public rule afterward stops new readers and takes nothing back from whoever already looked. Removing access notifies nobody, because Google offers no way to ask for it: they are not told, they find the calendar gone.

• GCAL_SHARING=off removes the sharing tools entirely, the wider ones included.

• An out-of-office or focus-time event that declines every meeting it overlaps, the ones you already accepted included, tells each organizer and is not taken back by deleting the event. create_event refuses auto_decline: all; create_event_declining_all makes it, and is registered only with GCAL_ENABLE_DECLINE_ALL=true, a flag of its own so that turning it on arms nothing else.

• Logs carry the method, tool, outcome, duration and a truncated calendar id. Never an email address, event title, description, location or search term. A debug log is safe to paste into a bug report by construction.

Your MCP client approves each call; the server does not ask you itself. claude.ai and Codex prompt for the tools marked destructive, cancel_event, create_event_declining_all, publish_calendar, widen_calendar_access, delete_calendar and clear_calendar, and VS Code prompts for every tool not marked read-only, which is every tool that writes. In Claude Code, delete_calendar, clear_calendar and publish_calendar ask on every call whatever your rules say: the first two delete a whole calendar's events, which Calendar cannot bring back, and the third opens a calendar to the internet or a domain, which removing the rule cannot take back. Where Claude Code cannot ask, as with -p, it refuses them. For the rest, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of google-calendar. For example, the writes that share, cancel, move, decline or delete:

{
  "permissions": {
    "ask": [
      "mcp__google-calendar__share_calendar", "mcp__google-calendar__unshare_calendar",
      "mcp__google-calendar__publish_calendar", "mcp__google-calendar__widen_calendar_access",
      "mcp__google-calendar__cancel_event", "mcp__google-calendar__move_event",
      "mcp__google-calendar__create_event_declining_all",
      "mcp__google-calendar__delete_calendar", "mcp__google-calendar__clear_calendar"
    ]
  }
}

Development

make check runs everything CI runs, and make parity asserts that those two lists are the same. See CONTRIBUTING.md.

Two things are run by hand rather than by CI, because they reach outside this repository. make live drives the built binary against a real account, on a scratch calendar it creates and deletes. make evals scores whether a model can complete the three tasks of docs/architecture.md §3 through these tools, against the in-memory calendar, and needs an ANTHROPIC_API_KEY; go run -tags=evals ./scripts/evals -self-check exercises the harness without a key or a model.

License

Apache 2.0. See LICENSE.