ical-mcp-server
Provides tools for managing iCloud calendar events through Calendar.app on macOS, including listing calendars, retrieving events in a date range, creating timed or all-day events, updating event details, and deleting events.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
English | 한국어
ical-mcp-server
A remote MCP server that creates, reads, updates, and deletes iCloud calendar events on a macOS server.
Read:
icalbuddyCLI (default), orosascript(JXA + EventKit) withICAL_MCP_READ_BACKEND=osascriptCreate, update, delete: controls Calendar.app via
osascriptTransport: MCP Streamable HTTP (stateless), reachable from outside the host
Authentication: API key
Tools
Tool | Description |
| Returns the list of calendars (name, type, uid). |
| Returns events in a date range. Defaults to the next 7 days starting today. Supports calendar filtering, keyword search, and a result limit. |
| Creates an event and returns its uid. If |
| Updates an event by uid. Only the fields you pass are changed; passing |
| Deletes an event by uid. |
Dates use the server's local time zone in YYYY-MM-DD or YYYY-MM-DDTHH:MM format. For all-day events, end is the last day (inclusive).
⚠️ All occurrences of a recurring event share the same uid, so
update_eventanddelete_eventapply to the entire series. Check therecurringfield in the response to see whether an event is recurring.
Related MCP server: Calendar Safe MCP
Installation
brew install ical-buddy
python3 -m venv .venv && .venv/bin/pip install -e .Building icalBuddy from source (without Homebrew)
If Homebrew is not installed or cannot be used, build icalBuddy from the same source the Homebrew formula uses (dkaluta/icalBuddy64). Only the Xcode Command Line Tools are required.
xcode-select --install # skip if already installed
curl -fsSL https://github.com/dkaluta/icalBuddy64/archive/refs/tags/v1.10.1.tar.gz | tar xz
cd icalBuddy64-1.10.1
# Build for the native architecture (the Makefile hardcodes x86_64)
sed -i '' -e 's/-arch x86_64//g' -e 's/-force_cpusubtype_ALL//g' Makefile
make icalBuddy COMPILER=clang APP_VERSION=1.10.1
sudo install -m 755 icalBuddy /usr/local/bin/icalbuddy
icalbuddy -VThe server looks for icalbuddy on PATH, then in /opt/homebrew/bin and /usr/local/bin. If you install it elsewhere, set ICALBUDDY_PATH to the binary's path.
macOS permissions (required)
Grant the following permissions to the process that runs the server (Terminal, iTerm, launchd, etc.):
System Settings → Privacy & Security → Calendars → Full Access Without this permission, icalBuddy fails with a
No calendarserror.System Settings → Privacy & Security → Automation → Calendar Required for writing via osascript. A permission prompt appears the first time you create an event.
An iCloud account must be connected in Calendar.app for changes to sync to iCloud.
Running
With run.sh (recommended)
run.sh takes care of setup and then starts the server:
./run.sh # port from .env (ICAL_MCP_PORT) or 8000
./run.sh 8765 # a bare number is treated as the port
./run.sh -p 8765 --path /mcp --log-level debug # other options are passed to the server as-is
./run.sh --read-backend osascript # read via osascript (EventKit) instead of icalbuddy
./run.sh --show-key # print the API key and connector settings, then exitOn each run it:
Creates
.venvwith Python 3.11+ and installs the package (again wheneverpyproject.tomlchanges).Loads
.env. If neitherICAL_MCP_API_KEYnorICAL_MCP_API_KEY_FILEis set, it generates a key and saves it to.env(mode600).With the
icalbuddyread backend, installs icalbuddy viabrew install ical-buddyif it is missing, and warns if it cannot read any calendars (usually a missing Calendar permission).Prints the local, LAN, and health-check URLs, then starts the server.
Put any of the environment variables below in .env to make them persistent, for example:
ICAL_MCP_API_KEY=...
ICAL_MCP_PORT=8765
ICAL_MCP_READ_BACKEND=osascriptRunning the server directly
# Generate an API key
export ICAL_MCP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
.venv/bin/ical-mcp-server --port 8765 # 0.0.0.0:8765/mcp
.venv/bin/ical-mcp-server --host 0.0.0.0 -p 9000 --path /mcpOptions
Option / Environment variable | Default | Description |
|
| Port |
|
| Bind address |
|
| MCP endpoint |
| (required) | API key. Multiple keys can be registered, separated by commas (e.g., one per user). |
| Path to a key file, one key per line. | |
|
| If |
|
| Seconds to wait for open connections on Ctrl+C/SIGTERM before cancelling them and exiting. |
|
| get_events logs the icalbuddy command, return code, stdout head, stderr and PATH/LANG/LC_ALL/TZ to stderr. |
| auto-detected | Path to the icalbuddy executable |
|
| Backend for |
GET /health responds without authentication and is intended for health checks.
Authentication
Send the API key in a request header, using either of the following:
Header | Example |
Bearer |
|
Custom header |
|
A missing or invalid key returns 401. Keys are compared in constant time.
Passing the key in the URL (/k/<KEY>/mcp, ?api_key=<KEY>) is disabled by default because the key may end up in access logs. Enable it with ICAL_MCP_ALLOW_URL_KEY=1 only for clients that cannot set headers.
Connecting as a Claude custom connector
Expose the server at a public HTTPS address, e.g., with an nginx reverse proxy and Let's Encrypt.
Configure the custom connector as follows:
URL:
https://your-domain.example.com/mcpRequest header:
Authorization: Bearer <KEY>orX-API-Key: <KEY>Leave the OAuth fields empty.
Run ./run.sh --show-key to display the key and configuration values. If the key is exposed, change ICAL_MCP_API_KEY in .env and restart the server.
Running persistently (launchd example)
~/Library/LaunchAgents/com.example.ical-mcp.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>com.example.ical-mcp</string>
<key>ProgramArguments</key><array>
<string>/path/to/ical-mcp-server/.venv/bin/ical-mcp-server</string>
<string>--port</string><string>8765</string>
</array>
<key>EnvironmentVariables</key><dict>
<key>ICAL_MCP_API_KEY_FILE</key><string>/Users/you/.config/ical-mcp/keys</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardErrorPath</key><string>/tmp/ical-mcp.log</string>
</dict></plist>Calendar and Automation permissions can only be granted when running as a LaunchAgent in a GUI login session.
Testing
.venv/bin/pip install -e ".[dev]" && .venv/bin/pytestTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Read and send iCloud Mail, manage iCloud Calendar. Needs an approved account at icloud.mcp.visin.ch.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables calendar management with iCloud through CalDAV, allowing users to list, create, update, and delete events via a standardized API.243 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to interact with Apple Calendar locally on macOS through EventKit, including listing calendars and events, creating events, and updating events with privacy-conscious safeguards.MIT
- AlicenseAqualityCmaintenanceEnables agents to read, create, update, and delete iCloud Calendar events, including recurring events, via CalDAV.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables remote MCP clients such as ChatGPT to read and search calendars, fetch events, and perform controlled writes to Apple iCloud calendars through CalDAV, with OAuth and server-enforced write policies.MIT