The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Calendar MCP listing page.
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.
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):
3. Sign in once, then add the server to your client:
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-mcpandcalendar-mcp-server, souvx calendar-mcp-serverand a localcalendar-mcpare the same command.
Claude Code
Claude Desktop — claude_desktop_config.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.
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.
Read-only tools never change anything. "Writes" tools create or modify events;
delete_event is the only one that destroys data.
Calendars and events
| Tool | Description | |
|---|---|---|
list_calendars | read | List the calendars the user can see, with IDs and timezones. |
find_events | read | Search a calendar for events, expanding recurring series into instances. |
check_attendee_status | read | Report who accepted, declined or has not answered an invitation. |
query_free_busy | read | Busy intervals for one or more calendars, without event details. |
analyze_busyness | read | Per-day event count and total scheduled minutes over a range. |
project_recurring_events | read | Compute future occurrences from recurrence rules. |
create_calendar | writes | Create a new secondary calendar. |
create_event | writes | Create an event with explicit start/end times and optional attendees. |
quick_add_event | writes | Create an event from a plain-English phrase, parsed by Google. |
update_event | writes | Change fields on an event; omitted fields are left untouched. |
move_event | writes | Reschedule an event, and/or move it to another calendar. |
add_attendee | writes | Invite one or more people to an existing event. |
respond_to_event | writes | Set your own RSVP (accepted/declined/tentative/needsAction). |
schedule_mutual | writes | Find the first slot where everyone is free, then book it. |
delete_event | destroys | Permanently delete an event. Asks the client to confirm via elicitation when supported. |
Scheduling brain — these read your saved preferences (working hours, lunch, buffer, minimum focus block).
| Tool | Description | |
|---|---|---|
find_focus_time | read | Uninterrupted blocks in a window that could be used for deep work, longest first. |
detect_conflicts | read | Double-bookings and too-tight transitions, across every signed-in account at once. |
time_audit | read | Where the time went: meeting hours, by size, domain, recurrence and person. |
suggest_reschedule | writes (opt-in) | Ranked better times for an existing meeting. Suggests only, unless apply: true. |
block_focus_time | writes | Book the best free blocks as focus time. dry_run: true to preview. |
Local configuration — no Google call, no account argument.
| Tool | Description | |
|---|---|---|
list_accounts | read | The accounts you have signed in, and which is the default. |
get_preferences | read | Working hours, lunch, buffer, minimum focus block, focus calendar. |
set_preferences | writes | Update and save those preferences. Local file only. |
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.
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_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 answers "how much of my week is meetings?" in one pass, grouped by
day or week:
Declined meetings, events marked free and all-day entries are left out by default;
include_declined and include_all_day bring them back.
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.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.You can sign in more than one Google account and pick between them per call.
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}.
Where things live. Tokens and preferences are stored in the OS user config
directory — %LOCALAPPDATA%\calendar-mcp on Windows, ~/.config/calendar-mcp
on Linux, ~/Library/Application Support/calendar-mcp on macOS — with one
token file per account under accounts/. Override the whole directory with
CALENDAR_MCP_CONFIG_DIR.
Back-compat. TOKEN_FILE_PATH still works and now means the default
account's token. If it is set, or if a .gcp-saved-tokens.json exists in the
working directory, that file is used for the default account and nothing
moves. Named accounts always live in the config directory.
The server remembers how you like your week to be shaped, so the scheduling
tools do not have to guess. Read them with get_preferences and change them
with set_preferences ("I start at 8 and I want 15 minutes between meetings").
Preferences are global — they describe you, not one account — and are stored as
preferences.json in the config directory.
| Field | Default | Meaning |
|---|---|---|
timezone | unset | IANA zone the working hours are expressed in, e.g. Europe/Berlin. |
working_hours | Mon–Fri 09:00–17:00 | Per weekday (mon…sun), a list of ["HH:MM", "HH:MM"] spans. |
buffer_minutes | 0 | Gap to leave either side of a meeting when proposing times. |
min_focus_block_minutes | 60 | Shortest free stretch that still counts as usable focus time. |
lunch | unset | A daily break carved out of the working hours. |
focus_calendar_id | primary | Calendar that focus blocks are booked on. |
set_preferences merges: only the arguments you pass change, and the merged
result is validated before it is written, so a rejected change leaves the saved
file untouched. The one exception is working_hours, which is a whole-schedule
replacement — weekdays you leave out of the dict become non-working days. Pass
clear_lunch: true to remove a lunch break.
| Variable | Default | Purpose |
|---|---|---|
GOOGLE_CLIENT_ID | — | OAuth client ID (required). |
GOOGLE_CLIENT_SECRET | — | OAuth client secret (required). |
TOKEN_FILE_PATH | .gcp-saved-tokens.json | Where the default account's OAuth token is cached. |
CALENDAR_MCP_CONFIG_DIR | OS user config dir | Directory holding per-account tokens (accounts/) and preferences.json. |
CALENDAR_MCP_DEFAULT_ACCOUNT | default | Account used when a tool's account argument is omitted. |
CALENDAR_SCOPES | https://www.googleapis.com/auth/calendar | Scope requested. Use .../auth/calendar.readonly for read-only. |
OAUTH_CALLBACK_PORT | 8080 | Local port for the OAuth callback during calendar-mcp auth. |
CALENDAR_MCP_ALLOW_BROWSER_AUTH | unset | Set to 1 to let the server itself open a browser when no token exists. Off by default so a stdio server never hangs. |
CALENDAR_MCP_LOG_FILE | unset | Mirror the stderr log to this file. |
CALENDAR_MCP_LOG_LEVEL | INFO | DEBUG/INFO/WARNING/ERROR/CRITICAL. Overrides --log-level. |
HOST | 127.0.0.1 | Default for --host in HTTP mode. |
PORT | 8000 | Default for --port in HTTP mode. |
A .env file in the working directory is loaded on startup. Logs never go to stdout — stdout is the MCP protocol channel in stdio mode.
python -m calendar_mcp accepts the same arguments.
http://localhost on any port for this client type, which is what the local callback on OAUTH_CALLBACK_PORT uses. Nothing to configure there.https://www.googleapis.com/auth/calendar scope, and add your own Google account as a test user. Without that last step the sign-in is rejected.Layout: calendar_mcp/server.py (the MCPServer, shared helpers and the credential provider), tools/ (one module per tool area — the tool functions themselves), calendar_actions.py (Google API calls), analysis.py, timeutil.py (pure interval maths), accounts.py (multi-account token paths), preferences.py (the saved schedule), models.py (pydantic input/output models), auth.py (OAuth), cli.py (the calendar-mcp command). scripts/smoke_stdio.py spawns a real stdio server and checks the handshake and tool list.
Nothing breaks. All 15 original tools keep their names and their existing
parameters; each simply gained an optional trailing account. Your existing
TOKEN_FILE_PATH keeps working, and now names the default account's token.
What is new: multiple accounts, saved scheduling preferences, and eight new
tools (find_focus_time, block_focus_time, detect_conflicts,
suggest_reschedule, time_audit, list_accounts, get_preferences,
set_preferences).
calendar-mcp-server and installs calendar-mcp (and an identical calendar-mcp-server alias). Point your client at uvx calendar-mcp-server instead of python /path/to/run_server.py.run_server.py still works — it is now a thin shim over the CLI — but it is deprecated and will be removed in a future release./health, and no separate stdio bridge process; the server is one process on the MCP SDK. If you want HTTP, it is now MCP streamable HTTP at /mcp.calendar-mcp auth once; the server will not open a browser unless CALENDAR_MCP_ALLOW_BROWSER_AUTH=1.move_event, respond_to_event, and project_recurring_events (the last previously existed only as internal logic).RELOAD, MCP_API_HOST. HOST/PORT now apply to the MCP HTTP transport.This project is dual-licensed to support both open-source collaboration and sustainable development:
GNU Affero General Public License v3.0 (AGPL-3.0):
Commercial License:
By using, modifying, or distributing this software, you agree to be bound by the terms of either the AGPLv3 or a separately negotiated commercial license.
mcp-name: io.github.deciduus/calendar-mcp