# 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

```bash
pip install calendar-mcp
```

## Configuration

Set three environment variables:

```bash
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

```json
{
  "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

```bash
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](LICENSE))
- **Commercial** — for proprietary use (see [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL))

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