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.

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.
• 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                # list them, with token paths and sign-in state

Every calendar tool takes an optional account argument naming one of these ("what's on my work calendar tomorrow?"). Omit it and the server uses the default: CALENDAR_MCP_DEFAULT_ACCOUNT if set, otherwise the account named default, otherwise the only account you have signed in. list_accounts returns the same list the CLI prints, so the model can discover the names itself.

Account names must match [A-Za-z0-9][A-Za-z0-9_-]{0,63}.