# Calendar MCP (one calendar, nothing else)

Remote MCP server that can read and write exactly one iCloud calendar
collection. Meant for a calendar named "Claude" that you create for this
purpose in Apple Calendar.

The restriction sits in the code, not in a permission dialog:
`ScopedCalendar` is given a fixed calendar URL and never calls
`principal()` or `calendars()`. There is no tool that could list or
address any other calendar of the account. The app-specific password for
the Apple ID technically covers the whole account, but nothing in the
server makes use of that.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_events(start, end)` | Events in a range, recurrences expanded |
| `get_event(uid)` | A single event |
| `create_event(...)` | Create, incl. all-day, RRULE, reminder |
| `update_event(uid, ...)` | Partial update, unset fields stay unchanged |
| `delete_event(uid)` | Delete |

Times without a timezone count as local time from `TIMEZONE`.

## Setup

### 1. Calendar and Apple app password

1. Create a new iCloud calendar in Apple Calendar, e.g. "Claude".
2. On appleid.apple.com, under "Sign-In and Security", generate an
   app-specific password.

### 2. Find the calendar URL

Locally, once:

```bash
pip install caldav
CALDAV_USERNAME=your@apple-id.tld \
CALDAV_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx \
python discover_calendar.py
```

The URL from the "Claude" line goes into the `.env` as
`CALDAV_CALENDAR_URL`. `discover_calendar.py` is deliberately not copied
into the image.

### 3. GitHub OAuth app

Claude signs in to the server via OAuth. GitHub only serves as proof of
identity here, so that not everyone who knows the URL can write.

Under GitHub → Settings → Developer settings → OAuth Apps, create an app:

- Homepage URL: `https://calendar-mcp.your-domain.tld`
- Authorization callback URL: `https://calendar-mcp.your-domain.tld/auth/callback`

Client ID and secret go into the `.env`. Set `ALLOWED_GITHUB_LOGINS` to
your own login: without that list, any GitHub account that knows the
server URL could sign in. That is why the server refuses to start when it
is empty.

### 4. Deployment on Coolify

New resource → Dockerfile-based, connect the repo.

- Port: `8000`
- Set a domain, let Coolify handle TLS
- `PUBLIC_BASE_URL` has to match the public domain exactly (without
  `/mcp`), otherwise OAuth discovery fails
- Enter every value from `.env.example` as an environment variable, mark
  secrets as such

The endpoint then lives at `https://<domain>/mcp`.

Test locally:

```bash
pip install -r requirements.txt
AUTH_MODE=none python server.py
```

### 5. Add it in Claude

Settings → Connectors → Add custom connector, URL
`https://calendar-mcp.your-domain.tld/mcp`. Client ID and secret stay
empty, dynamic client registration does the rest. The GitHub login
follows, and the connector is then available in all Claude interfaces,
mobile included.

## When something does not connect

- Claude waits at most 10 seconds for the OAuth endpoints. A container
  starting cold runs into that timeout, so warm it up once.
- A `PUBLIC_BASE_URL` with a diverging host or path is the most common
  cause of a failing discovery.
- Anthropic's outbound requests come from `160.79.104.0/21`. If you put a
  firewall in front of it anyway, you can narrow it down to that.

## What the server cannot do

- No other calendars, not even on request.
- No attendees, no invitations, no free/busy.
- Nothing runs by itself. The server only acts when Claude calls it in a
  conversation or in a scheduled task.

One note on security: titles and descriptions of events end up as text in
the model context. As long as the calendar stays unshared and receives no
outside invitations, you are the only one writing into it.