MCP 服务器

Calendar MCP

Enables reading and writing events to a single iCloud calendar, with support for recurring events and reminders, scoped to a specific calendar.

README

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

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

2. Find the calendar URL

Locally, once:

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:

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.