Calendar MCP

calendar-mcp

An MCP server that gives an LLM client read and write access to your Google Calendar. It runs as a single process — stdio by default, streamable HTTP optionally — and exposes 23 tools with structured output: listing and searching calendars and events, creating, updating, moving, RSVPing to and deleting events, free/busy queries, busyness analysis, recurring-event projection, and finding a mutual slot and booking it. On top of that it has a scheduling brain that knows your working hours: finding and booking focus time, detecting double-bookings across several accounts at once, proposing better times for a meeting, and auditing where your week actually went. Authentication is Google OAuth 2.0 (Desktop app flow); tokens are cached locally, per account, and refreshed automatically.

A calendar task, end to end

Synthetic example, backed by offline tests; no real calendar data or live booking. Assume Thursday working hours of 09:00–17:00 UTC, one meeting at 11:00–12:00, no lunch or buffer, and a 60-minute minimum focus block.

“Find six hours of focus time on January 1, 2026. Show me the blocks first.”

An MCP client can call:

{

"tool": "block_focus_time", "arguments": { "time_min": "2026-01-01T00:00:00Z", "time_max": "2026-01-02T00:00:00Z", "hours_needed": 6, "dry_run": true } }

The preview selects 09:00–10:00 and 12:00–17:00: six hours, with the last selected block trimmed to the remaining hour. Both events have created: false. After the user approves the times, the client can call with dry_run: false; availability is read again before creating events. A preview does not reserve a slot.

Design decision: unknown availability is not free time. If a checked calendar returns an access error, disappears from the response, or has unreadable busy intervals, focus search and booking return an error before writing anything. The same check protects mutual scheduling and reschedule suggestions/application. For example, a notFound response for work@example.com becomes:

Availability is unknown: work@example.com: notFound. No scheduling changes were made.

Restore calendar access or retry the query.

Reproduce the preview and the safety regression without Google credentials (after the development install):

pytest -q tests/test_scheduling.py -k 'focus_time_dry_run or focus_refuses_unknown'

The regression verifies that partial, missing and errored availability never calls create_event, in both preview and booking modes. Successful empty busy lists still mean genuinely free time. Availability checks and writes are separate Google API calls, so another client can still book a competing event between them.

Quick start

1. Create Google OAuth credentials. In the Google Cloud console, enable the Google Calendar API, then create an OAuth client ID of type Desktop app. Copy the client ID and secret. (Details in Google Cloud setup.)

2. Set them in your environment, or in a .env file in the directory you run from (see example.env):

GOOGLE_CLIENT_ID='...'

GOOGLE_CLIENT_SECRET='...'

3. Sign in once, then add the server to your client:

uvx calendar-mcp-server auth

This opens a browser and saves a token in the config directory (see Accounts); if you already have a .gcp-saved-tokens.json or set TOKEN_FILE_PATH, that file is used instead. Verify it with calendar-mcp check. Add more Google accounts with calendar-mcp auth --account work. After that the server runs non-interactively — it never opens a browser on its own unless you set CALENDAR_MCP_ALLOW_BROWSER_AUTH=1.

The PyPI distribution is calendar-mcp-server. It installs two identical console scripts, calendar-mcp and calendar-mcp-server, so uvx calendar-mcp-server and a local calendar-mcp are the same command.

Client configuration

Claude Code

claude mcp add calendar \

--env GOOGLE_CLIENT_ID=... \ --env GOOGLE_CLIENT_SECRET=... \ -- uvx calendar-mcp-server

Claude Desktop — claude_desktop_config.json:

{

"mcpServers": { "calendar": { "command": "uvx", "args": ["calendar-mcp-server"], "env": { "GOOGLE_CLIENT_ID": "...", "GOOGLE_CLIENT_SECRET": "...", "TOKEN_FILE_PATH": "/absolute/path/to/.gcp-saved-tokens.json" } } } }

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global): same mcpServers block as above.

Any other client that speaks the standard mcpServers JSON takes the same entry. TOKEN_FILE_PATH is optional now that tokens default to the OS config directory, which does not depend on the working directory the client picks — but if you do set it, make it an absolute path.

Remote / HTTP mode

calendar-mcp --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is then http://127.0.0.1:8000/mcp (change the path with --path).

There is no authentication layer on the HTTP transport yet. Anyone who can reach the endpoint gets full access to the calendar the saved token belongs to. Bind it to loopback, or expose it only behind a trusted reverse proxy that authenticates, or on a private network such as a tailnet. Do not put it on a public interface.

Tools

Read-only tools never change anything. "Writes" tools create or modify events; delete_event is the only one that destroys data.

Calendars and events

Scheduling brain — these read your saved preferences (working hours, lunch, buffer, minimum focus block).

Local configuration — no Google call, no account argument.

Every calendar tool takes an optional trailing account argument (detect_conflicts takes accounts, a list, because checking several at once is the point). All times are ISO 8601 strings — a naive timestamp is interpreted in the target calendar's own timezone.

Scheduling brain

The five scheduling tools share one idea: your calendar is not the same as your availability. They start from your working hours, subtract lunch, subtract what is already booked, and subtract the buffer you want around meetings — then reason about what is left.

Prompts that exercise them:

• "Find me six hours of focus time next week and block it out — show me the times first."
• "Is anything double-booked between my work and personal calendars this week?"
• "My Thursday is back-to-back. Suggest better times for the design review."
• "Where did my time go last month? Who am I spending it with?"
• "I need a 90-minute deep work block before Friday. Is there one?"

find_focus_time reports what exists; block_focus_time defends it by creating events (busy, reminders off, nobody notified), trimming the last block so it books exactly the hours you asked for rather than a whole afternoon. detect_conflicts separates genuine overlaps from *tight* transitions that merely break your buffer, and ignores events you declined, events marked free, and (by default) all-day entries. suggest_reschedule keeps the meeting's duration, ranks candidate slots by fewest attendee conflicts and prefers the event's current day, and moves nothing unless you pass apply: true.

Time audit

time_audit answers "how much of my week is meetings?" in one pass, grouped by day or week:

2026-08-01 .. 2026-09-01, Europe/Berlin, grouped by week

Meetings: 41.5 h across 63 meetings Working hours: 152.0 h available (lunch removed) In working hours: 38.0 h -> 25% of the week Busiest week: 2026-W34, 14.0 h Heaviest day: 2026-08-20, 6.5 h By size: 1:1 18.0 h | small 15.5 h | large 8.0 h By recurrence: recurring 26.0 h | one-off 15.5 h Top people: a.schmidt@example.com 9.0 h | j.lee@example.com 7.5 h

Declined meetings, events marked free and all-day entries are left out by default; include_declined and include_all_day bring them back.

Safety

• `delete_event` is the only destructive tool. It asks the client to confirm through MCP elicitation when the client supports it, and proceeds normally when it does not.
• `block_focus_time` takes `dry_run`. Run it with dry_run: true to see the exact blocks it would book before anything is written. The destination calendar is always included in the availability check.
• Scheduling fails closed on unknown availability. Focus search/booking, both mutual-scheduling paths, and reschedule suggestions/application require readable availability for every checked calendar. Errors are returned before writes, rather than warnings after booking. Restore access or retry before scheduling. Default focus-calendar discovery also refuses an incomplete, paginated calendar list; supply an explicit complete list with calendar_ids / check_calendar_ids in that case.
• `suggest_reschedule` does not move anything by default. apply is false and has to be set explicitly, once the user has agreed to a time.
• Everything else that writes is additive — creating or editing an event — and update_event leaves fields you omit untouched.
• `list_accounts`, `get_preferences` and `set_preferences` never touch Google. They read and write local files in the config directory.

Accounts

You can sign in more than one Google account and pick between them per call.

calendar-mcp auth                    # the default account

calendar-mcp auth --account work # a second, named account calendar-mcp accounts