calendar-mcp

Provider-agnostic CalDAV calendar MCP server for AI assistants. Connect any CalDAV calendar to Claude Desktop, Cursor, VS Code, or any MCP-compatible client.

Features

• 10 calendar tools: list_calendars, get_events, get_event, today, upcoming, search_events, free_busy, create_event, update_event, delete_event
• Provider auto-detection: Automatically configures Google, Apple iCloud, Nextcloud, Fastmail from your CalDAV URL
• Any CalDAV server: Works with Radicale, Baikal, ownCloud, or any standard CalDAV provider
• Read-only mode: Optional safety mode that disables all write operations
• Zero external dependencies: Pure Python stdlib for CalDAV/iCal (only mcp SDK required)
• RFC 5545 compliant: Proper iCalendar parsing with recurrence rules, durations, timezones, attendees

Quick Start

pip install calendar-mcp

Configuration

Set three environment variables:

export CALENDAR_MCP_URL="https://caldav.icloud.com/"
export CALENDAR_MCP_USERNAME="you@icloud.com"
export CALENDAR_MCP_PASSWORD="your-app-password"

All Environment Variables

Variable	Required	Default	Description
CALENDAR_MCP_URL	Yes	—	CalDAV server URL
CALENDAR_MCP_USERNAME	Yes	—	Username (usually email)
CALENDAR_MCP_PASSWORD	Yes	—	Password or app-specific password
CALENDAR_MCP_PROVIDER	No	Auto-detected	Force provider: google, apple, nextcloud, fastmail, generic
CALENDAR_MCP_CALENDAR_ID	No	First calendar	Default calendar name
CALENDAR_MCP_READ_ONLY	No	false	Set to true to disable write operations
CALENDAR_MCP_TIMEZONE	No	UTC	Default timezone

Provider Auto-Detection

URL Pattern	Provider	Default CalDAV URL
googleusercontent.com	google	https://apidata.googleusercontent.com/caldav/v2/
caldav.icloud.com	apple	https://caldav.icloud.com/
office365.com	outlook	https://outlook.office365.com/caldav/v2/
caldav.fastmail.com	fastmail	https://caldav.fastmail.com/dav/calendars/user/{email}/
nextcloud, owncloud	nextcloud	(your server URL)
anything else	generic	(your server URL)

Client Configuration

Claude Desktop

{
  "mcpServers": {
    "calendar": {
      "command": "calendar-mcp",
      "env": {
        "CALENDAR_MCP_URL": "https://caldav.icloud.com/",
        "CALENDAR_MCP_USERNAME": "you@icloud.com",
        "CALENDAR_MCP_PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code

claude mcp add -e CALENDAR_MCP_URL=https://caldav.icloud.com/ -e CALENDAR_MCP_USERNAME=you@icloud.com -e CALENDAR_MCP_PASSWORD=your-app-password calendar calendar-mcp

Tools

Tool	Description	Write?
list_calendars	List all calendars on the account	No
get_events	Get events in a date range (configurable days ahead/back)	No
get_event	Get a single event by UID	No
today	Get all events for today	No
upcoming	Get events in the next N hours	No
search_events	Search by text in title, description, location	No
free_busy	Free/busy summary with total hours	No
create_event	Create a new event	Yes
update_event	Update an existing event (partial updates)	Yes
delete_event	Delete an event by UID	Yes

Write tools are disabled when CALENDAR_MCP_READ_ONLY=true.

License

Dual-licensed:

• AGPL-3.0 — free for open-source use (see LICENSE)
• Commercial — for proprietary use (see LICENSE-COMMERCIAL)

<!-- mcp-name: io.github.p-w-4-z/calendar-mcp -->