Skip to content
Back to search

ical-mcp-server

A remote MCP server that creates, reads, updates, and deletes iCloud calendar events on a macOS server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jaesimio--ical-mcp-server/badge.svg)](/listings/jaesimio--ical-mcp-server)

HTML

<a href="/listings/jaesimio--ical-mcp-server"><img src="/api/listings/jaesimio--ical-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/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 -V

The server looks for `icalbuddy` on `PATH`, then in `/opt/homebrew/bin` and `/usr/local/bin`, and finally falls back to the prebuilt universal binary bundled at `lib/icalBuddy` (icalBuddy 1.10.1, MIT; see [LICENSE](LICENSE)). 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.):

1. **System Settings → Privacy & Security → Calendars → Full Access** Without this permission, icalBuddy fails with a `No calendars` error. 2. **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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 171 lines
  1. **English** | [한국어](README.ko.md)
  2. # ical-mcp-server
  3. A remote MCP server that creates, reads, updates, and deletes iCloud calendar events on a macOS server.
  4. - **Read**: `icalbuddy` CLI (default), or `osascript` (JXA + EventKit) with `ICAL_MCP_READ_BACKEND=osascript`
  5. - **Create, update, delete**: controls Calendar.app via `osascript`
  6. - **Transport**: MCP Streamable HTTP (stateless), reachable from outside the host
  7. - **Authentication**: API key
  8. ## Tools
  9. | Tool | Description |
  10. |---|---|
  11. | `list_calendars` | Returns the list of calendars (name, type, uid). |
  12. | `get_events` | Returns events in a date range. Defaults to the next 7 days starting today. Supports calendar filtering, keyword search, and a result limit. |
  13. | `create_event` | Creates an event and returns its uid. If `start` is in `YYYY-MM-DD` format, an all-day event is created. |
  14. | `update_event` | Updates an event by uid. Only the fields you pass are changed; passing `""` clears that field. If you change only the start time, the original duration is kept. |
  15. | `delete_event` | Deletes an event by uid. |
  16. 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).
  17. > ⚠️ All occurrences of a recurring event share the same uid, so `update_event` and `delete_event` apply to the **entire series**. Check the `recurring` field in the response to see whether an event is recurring.
  18. ## Installation
  19. ```bash
  20. brew install ical-buddy
  21. python3 -m venv .venv && .venv/bin/pip install -e .
  22. ```
  23. ### Building icalBuddy from source (without Homebrew)
  24. If Homebrew is not installed or cannot be used, build icalBuddy from the same source the Homebrew formula uses ([dkaluta/icalBuddy64](https://github.com/dkaluta/icalBuddy64)). Only the Xcode Command Line Tools are required.
  25. ```bash
  26. xcode-select --install # skip if already installed
  27. curl -fsSL https://github.com/dkaluta/icalBuddy64/archive/refs/tags/v1.10.1.tar.gz | tar xz
  28. cd icalBuddy64-1.10.1
  29. # Build for the native architecture (the Makefile hardcodes x86_64)
  30. sed -i '' -e 's/-arch x86_64//g' -e 's/-force_cpusubtype_ALL//g' Makefile
  31. make icalBuddy COMPILER=clang APP_VERSION=1.10.1
  32. sudo install -m 755 icalBuddy /usr/local/bin/icalbuddy
  33. icalbuddy -V
  34. ```
  35. The server looks for `icalbuddy` on `PATH`, then in `/opt/homebrew/bin` and `/usr/local/bin`, and finally falls back to the prebuilt universal binary bundled at `lib/icalBuddy` (icalBuddy 1.10.1, MIT; see [LICENSE](LICENSE)). If you install it elsewhere, set `ICALBUDDY_PATH` to the binary's path.
  36. ### macOS permissions (required)
  37. Grant the following permissions to the process that runs the server (Terminal, iTerm, launchd, etc.):
  38. 1. **System Settings → Privacy & Security → Calendars → Full Access**
  39. Without this permission, icalBuddy fails with a `No calendars` error.
  40. 2. **System Settings → Privacy & Security → Automation → Calendar**
  41. Required for writing via osascript. A permission prompt appears the first time you create an event.
  42. An iCloud account must be connected in Calendar.app for changes to sync to iCloud.
  43. ## Running
  44. ### With `run.sh` (recommended)
  45. `run.sh` takes care of setup and then starts the server:
  46. ```bash
  47. ./run.sh # port from .env (ICAL_MCP_PORT) or 8000
  48. ./run.sh 8765 # a bare number is treated as the port
  49. ./run.sh -p 8765 --path /mcp --log-level debug # other options are passed to the server as-is
  50. ./run.sh --read-backend osascript # read via osascript (EventKit) instead of icalbuddy
  51. ./run.sh --show-key # print the API key and connector settings, then exit
  52. ```
  53. On each run it:
  54. 1. Creates `.venv` with Python 3.11+ and installs the package (again whenever `pyproject.toml` changes).
  55. 2. Loads `.env`. If neither `ICAL_MCP_API_KEY` nor `ICAL_MCP_API_KEY_FILE` is set, it generates a key and saves it to `.env` (mode `600`).
  56. 3. With the `icalbuddy` read backend, uses the bundled `lib/icalBuddy` if icalbuddy is not on `PATH`, and warns if it cannot read any calendars (usually a missing Calendar permission).
  57. 4. Prints the local, LAN, and health-check URLs, then starts the server.
  58. Put any of the environment variables below in `.env` to make them persistent, for example:
  59. ```bash
  60. ICAL_MCP_API_KEY=...
  61. ICAL_MCP_PORT=8765
  62. ICAL_MCP_READ_BACKEND=osascript
  63. ```
  64. ### Running the server directly
  65. ```bash
  66. # Generate an API key
  67. export ICAL_MCP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
  68. .venv/bin/ical-mcp-server --port 8765 # 0.0.0.0:8765/mcp
  69. .venv/bin/ical-mcp-server --host 0.0.0.0 -p 9000 --path /mcp
  70. ```
  71. ### Options
  72. | Option / Environment variable | Default | Description |
  73. |---|---|---|
  74. | `--port`, `-p` / `ICAL_MCP_PORT` | `8000` | Port |
  75. | `--host` / `ICAL_MCP_HOST` | `0.0.0.0` | Bind address |
  76. | `--path` / `ICAL_MCP_PATH` | `/mcp` | MCP endpoint |
  77. | `ICAL_MCP_API_KEY` | (required) | API key. Multiple keys can be registered, separated by commas (e.g., one per user). |
  78. | `ICAL_MCP_API_KEY_FILE` | | Path to a key file, one key per line. |
  79. | `ICAL_MCP_ALLOW_URL_KEY` | `0` | If `1`, keys passed in the URL (path or query) are also accepted. |
  80. | `--shutdown-timeout` / `ICAL_MCP_SHUTDOWN_TIMEOUT` | `5` | Seconds to wait for open connections on Ctrl+C/SIGTERM before cancelling them and exiting. |
  81. | `--log-level` | `info` | get_events logs the icalbuddy command, return code, stdout head, stderr and PATH/LANG/LC_ALL/TZ to stderr. |
  82. | `ICALBUDDY_PATH` | auto-detected | Path to the icalbuddy executable |
  83. | `--read-backend` / `ICAL_MCP_READ_BACKEND` | `icalbuddy` | Backend for `list_calendars`/`get_events`: `icalbuddy` or `osascript`. `osascript` reads through EventKit via JXA (no icalbuddy needed, recurring events expanded, uids identical to Calendar.app). It needs Calendar access for the app running the server; on first use macOS shows the permission prompt. |
  84. `GET /health` responds without authentication and is intended for health checks.
  85. ## Authentication
  86. Send the API key in a request header, using either of the following:
  87. | Header | Example |
  88. |---|---|
  89. | Bearer | `Authorization: Bearer <KEY>` |
  90. | Custom header | `X-API-Key: <KEY>` |
  91. A missing or invalid key returns `401`. Keys are compared in constant time.
  92. 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.
  93. ## Connecting as a Claude custom connector
  94. 1. Expose the server at a **public HTTPS address**, e.g., with an nginx reverse proxy and Let's Encrypt.
  95. 2. Configure the custom connector as follows:
  96. - URL: `https://your-domain.example.com/mcp`
  97. - Request header: `Authorization: Bearer <KEY>` or `X-API-Key: <KEY>`
  98. - Leave the OAuth fields empty.
  99. 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.
  100. ## Running persistently (launchd example)
  101. `~/Library/LaunchAgents/com.example.ical-mcp.plist`:
  102. ```xml
  103. <?xml version="1.0" encoding="UTF-8"?>
  104. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  105. <plist version="1.0"><dict>
  106. <key>Label</key><string>com.example.ical-mcp</string>
  107. <key>ProgramArguments</key><array>
  108. <string>/path/to/ical-mcp-server/.venv/bin/ical-mcp-server</string>
  109. <string>--port</string><string>8765</string>
  110. </array>
  111. <key>EnvironmentVariables</key><dict>
  112. <key>ICAL_MCP_API_KEY_FILE</key><string>/Users/you/.config/ical-mcp/keys</string>
  113. </dict>
  114. <key>RunAtLoad</key><true/>
  115. <key>KeepAlive</key><true/>
  116. <key>StandardErrorPath</key><string>/tmp/ical-mcp.log</string>
  117. </dict></plist>
  118. ```
  119. Calendar and Automation permissions can only be granted when running as a LaunchAgent in a GUI login session.
  120. ## Testing
  121. ```bash
  122. .venv/bin/pip install -e ".[dev]" && .venv/bin/pytest
  123. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.