ical-mcp
Provides tools for managing Apple Calendar events via CalDAV, including listing calendars, querying events, creating, updating, deleting events, and checking free/busy status.
Provides tools for managing iCloud calendars via CalDAV, supporting event CRUD operations and free/busy queries.
Provides tools for managing Nextcloud calendars via CalDAV, supporting event CRUD operations and free/busy queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ical-mcp list my events for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ical-mcp
MCP server for Apple Calendar and CalDAV providers.
Works with iCloud, Fastmail, Nextcloud, and any CalDAV-compatible calendar. No macOS dependency — runs headless on any platform.
Quick start
# Install
uvx ical-mcp
# Or from source
uv sync
uv run ical-mcpRelated MCP server: iCloud CalDAV MCP Connector
Configuration
Set these environment variables (or copy .env.example to .env):
Variable | Required | Description |
| Yes | CalDAV server URL (e.g. |
| Yes | Your email / account ID |
| Yes | Password or app-specific password |
| No | Default timezone (default: |
| No | Calendars that allow writes (see Write protection) |
iCloud setup
Go to account.apple.com → Sign-In and Security → App-Specific Passwords
Generate a new password (label it "ical-mcp")
Set
ICAL_MCP_URL=https://caldav.icloud.comSet
ICAL_MCP_USERNAMEto your Apple ID emailSet
ICAL_MCP_PASSWORDto the generated app-specific password
Tools
Tool | Description |
| List all available calendars (shows read/write access per calendar) |
| Query events by date range |
| Create a new event |
| Update an existing event (partial patch, only changed fields) |
| Delete an event |
| Check busy/free status for a time range |
Write protection
All calendars are read-only by default. You must explicitly opt in to writes:
# Single calendar (by name or ID)
ICAL_MCP_WRITABLE_CALENDARS=home
# Multiple calendars
ICAL_MCP_WRITABLE_CALENDARS=home,Work
# All calendars (use with caution)
ICAL_MCP_WRITABLE_CALENDARS=*
# Not set or empty — all calendars are read-onlylist_calendars shows "access": "read-only" or "access": "read-write" for each calendar, so the AI agent knows what it can and can't modify.
Using calendar IDs (UUIDs) instead of names avoids issues with spaces and renames.
Transport
# Local use with Claude Code / Claude Desktop (default)
ical-mcp
# Shared HTTP server for multi-agent access
ical-mcp --transport http --port 8093
# Bind to a specific address (e.g. Tailscale IP)
ical-mcp --transport http --host 100.64.0.1 --port 8093Claude Code configuration
Local (stdio)
{
"mcpServers": {
"ical-mcp": {
"command": "uvx",
"args": ["ical-mcp"],
"env": {
"ICAL_MCP_URL": "https://caldav.icloud.com",
"ICAL_MCP_USERNAME": "your@icloud.com",
"ICAL_MCP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
"ICAL_MCP_WRITABLE_CALENDARS": "your-calendar-id"
}
}
}
}Remote (HTTP)
{
"mcpServers": {
"ical-mcp": {
"url": "http://your-server:8093/mcp"
}
}
}Safety features
Per-calendar write protection — read-only by default, explicit opt-in per calendar
Backup before mutate — every update/delete logs the full iCal data to stderr
ETag concurrency — updates fail if the event was modified elsewhere since last fetch
Semantic errors — clear messages for auth failures, rate limits, conflicts, and read-only violations
License
MIT
Available Tools
6 toolscreate_eventA
Create a new calendar event.
Confirm the calendar, date, time, and details with the user before calling. Returns the created event with its ID and ETag for future updates.
Inputs: title (required), start (required), end (required), calendar, +3 more. Returns: result
delete_eventA
Delete a calendar event.
Confirm with the user before deleting. Pass the ETag from get_events to ensure you're deleting the right version.
Inputs: event_id (required), calendar, etag. Returns: result
get_eventsA
Get events within a date range.
Returns events sorted by start time. Recurring events are returned as individual expanded occurrences within the requested range.
Inputs: start (required), end (required), calendar. Returns: result
get_freebusyA
Check free/busy status for a time range.
Returns a list of busy time blocks within the requested range. Useful for finding available slots before scheduling.
Inputs: start (required), end (required), calendar. Returns: result
list_calendarsA
List all available calendars.
Returns calendar names and IDs for use with other tools. Call this first to discover which calendars exist before querying or creating events.
Inputs: no named parameters. Returns: result
update_eventA
Update an existing calendar event.
Only send the fields you want to change — unchanged fields are preserved. Requires the event's ETag for optimistic concurrency; if the event was modified elsewhere, the update will fail with a conflict error.
Inputs: event_id (required), etag (required), calendar, title, +4 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clear, distinct purpose: create, delete, get, update events, plus free/busy and list calendars. No overlap or ambiguity.
All tools use a consistent verb_noun pattern in snake_case (e.g., create_event, list_calendars). No deviations or mixed conventions.
With 6 tools, the set is well-scoped for a calendar MCP server: covers CRUD for events and essential utilities without being bloated or sparse.
Covers core calendar operations (CRUD events, free/busy, list calendars). Minor gap: lacks advanced event search (e.g., by title) but handles typical workflows well.
Related MCP Connectors
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
A MCP server that works with Google Calendar to manage event listing, reading, and updates.
EU-hosted calendar MCP: Google, Outlook, iCloud, GMX, WEB.DE, CalDAV. Read, book, RSVP, sync.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for accessing macOS Calendar events2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with iCloud Calendars via the CalDAV protocol using an app-specific password. It allows users to list, create, update, and delete calendar events through MCP-aware clients like ChatGPT.2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar via native EventKit API with proper recurring event support.24 npm10MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar, Mail, Reminders, and Files on macOS using native frameworks.24 npm22MIT