calendar-mcpAn MCP server that lets an AI chat clientread and book a calendar. It exposes three tools over stdio JSON-RPC, so anyMCP client (opencode, Claude Desktop, …) can schedule meetings from a normalchat.- check_calendar(start_date, end_date, timezone=None) — busy events and free 30-minute slots per day; ind_slot ranks multi-person options with explanations- book_slot(person, date, start, duration_minutes=30, title=None, timezone=None) — books a slot, rejecting any overlap with an existing eventThe server implements the Model Context Protocol by hand with only the Pythonstandard library — nothing to install except tzdata on Windows fortimezone support. State lives in a plain JSON file (calendar.json).## Why it’s differentThe never-double-book rule is enforced in code, not in a prompt. book_slottakes a cross-process lock, re-reads every event, and refuses overlaps, writingatomically (os.replace) — so a misbehaving model or a concurrent caller cannotcreate a conflict. Times are timezone-aware (IANA zones), and overlaps arecompared as absolute instants (DST-safe).## Quick startbashpip install tzdata # Windows only; Linux/macOS already have the tz databasepython seed_calendar.py # write a sample calendar.json (dates relative to today)python mcp_server.py # run the MCP server on stdio (usually launched by a client)## Register with a clientThe client launches the server as a stdio process. Example for opencode’sopencode.json:json{ "$schema": "https://opencode.ai/config.json", "mcp": { "calendar-mcp": { "type": "local", "command": ["python", "calendar-mcp/mcp_server.py"], "enabled": true } }}Claude Desktop uses the same shape in claude_desktop_config.json:json{ "mcpServers": { "calendar-mcp": { "command": "python", "args": ["/absolute/path/to/calendar-mcp/mcp_server.py"] } }}Restart the client, then ask in normal language:> Book 30 minutes with Sam next Tuesday at 10:00.\n\nThe client can call check_calendar to inspect free slots, use find_slot to get a cross-timezone optimal list with explanations, and then book_slot to book.## Tools### find_slot (constraint-aware scheduling)\n\n| field | type | notes |\n| — | — | — |\n| duration_minutes | integer? | meeting length (default 30) |\n| start_date | string? | first day to search (defaults to today, organizer tz) |\n| end_date | string? | last day to search (defaults to +7 days) |\n| max_results | integer? | how many ranked options to return (default 5) |\n| min_notice_minutes | integer? | minimum lead time (default 0) |\n\nReads participants.json (list of people with timezones, working hours, buffers, events, preferences). Returns ranked options with local_times, score_breakdown, and human-readable reasons. Hard constraints (work days/hours, busy+buffer, min notice) are enforced; soft preferences (fairness across timezo