io.github.IceyWu/icloud-calendar
Manage Apple iCloud Calendar through a reliable CalDAV MCP server.
Open source Open in the app JSON README (API)
About
Manage Apple iCloud Calendar through a reliable CalDAV MCP server.
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- iceywu
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Last push
- 2026-08-18T07:12:58Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:58
- Updated
- 2026-08-29 03:01:58
- Origin id
io.github.IceyWu/icloud-calendar
README
<p align="center">
<img src="assets/logo.svg" width="120" alt="iCloud Calendar MCP logo">
</p>
<h1 align="center">iCloud Calendar MCP</h1>
<p align="center">
An MCP server for managing iCloud Calendar.
</p>
<p align="center">
<strong>English</strong> · <a href="docs/README.zh-CN.md">简体中文</a>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/icloud-calendar-mcp"></a>
<a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/icloud-calendar-mcp"></a>
<a href="https://github.com/IceyWu/icloud-calendar-mcp/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/IceyWu/icloud-calendar-mcp/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="Node.js version" src="https://img.shields.io/node/v/icloud-calendar-mcp"></a>
<a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/icloud-calendar-mcp"></a>
</p>
## Setup
Requirements:
- Node.js 22.13 or later
- Your Apple Account email
- An Apple [app-specific password](https://support.apple.com/102654)
Add the server to your MCP client:
```json
{
"mcpServers": {
"icloud-calendar": {
"command": "npx",
"args": ["-y", "icloud-calendar-mcp"],
"env": {
"ICLOUD_USERNAME": "you@example.com",
"ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
}
}
}
}
```
Use an app-specific password, not your Apple Account password.
## Tools
| Tool | Purpose |
| ---------------- | --------------------------- |
| `list_calendars` | List calendars |
| `list_events` | List events in a time range |
| `get_event` | Get an event |
| `create_event` | Create an event |
| `update_event` | Update an event |
| `delete_event` | Delete an event |
| `find_conflicts` | Find overlapping events |
| `free_busy` | Return busy time ranges |
Events can include time zones, all-day dates, recurrence rules, alarms, locations, descriptions, URLs, and attendees.
## Example requests
Once the server is connected, you can ask your MCP client:
> Show my calendars.
> What is on my calendar next week in Asia/Shanghai time?
> Add a project review to my Work calendar tomorrow from 2:00 PM to 3:00 PM, with a reminder 15 minutes before.
> Do I have any conflicts on Friday between 9:00 AM and noon?
> Move the project review to 4:00 PM and change the location to Meeting Room B.
> Add an all-day event called “Company holiday” on October 1.
> Delete the project review event.
For ambiguous requests, include the calendar, date, time, and time zone when possible.
## Behavior
- All-day event end dates are exclusive. A one-day event on August 18 uses `2026-08-18` to `2026-08-19`.
- Create, update, and delete operations accept a `request_id` for safe retries.
- Concurrent changes are detected with ETags.
- Whole recurring series can be updated or deleted. Unsupported occurrence-level changes return an error instead of modifying the series.
See [tool contracts](docs/tool-contracts.md) for complete inputs, outputs, and error codes.
## HTTP
stdio is the default transport. Streamable HTTP is optional:
```bash
ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx -y icloud-calendar-mcp
```
HTTP mode requires a bearer token and listens on loopback by default. See [security](docs/security.md) before exposing it through a proxy.
## Development
```bash
pnpm install
pnpm check
```
See [architecture](docs/architecture.md), [contributing](CONTRIBUTING.md), and [releasing](docs/releasing.md).
## License
[MIT](LICENSE)