icloud-mcp server

icloud-mcp

This unified Apple/iCloud MCP server supports Calendar, Contacts, and Mail. It is one static Go binary. It uses Model Context Protocol JSON-RPC on stdio.

The server uses only remote protocols: CalDAV, CardDAV, IMAP, and SMTP with app-specific passwords. It does not use macOS EventKit, AppleScript, browser automation, or a private Apple API. It runs headless on Linux and macOS. Pure Go also builds for Windows.

CI runs a windows/amd64 smoke build. GitHub Release archives contain linux/amd64, linux/arm64, and darwin/arm64 builds. Agents, orchestrators, and desktop chat applications can use the server.

Host-agnostic. Any MCP client can use the server if it starts child processes with an environment and connects stdin and stdout. Compatible clients include personal agents, Hermes, OpenClaw, IDE bridges, runners, and other stdio hosts. The server does not prefer a model vendor, chat product, or reseller. Configure the server only through its process environment. The binary does not parse host-specific config files or .env.

Reminders, Notes, Photos, Drive, Messages, and similar apps are out of scope. They remain out of scope until Apple documents a suitable remote third-party connector. See Supported scope.

Quick start

go install github.com/ThomasCrouzet/icloud-mcp/cmd/icloud-mcp@latest
# or: make build
# or: make release VERSION=v0.4.0
# or: make release-all VERSION=v0.4.0

main Apple Account password.

1. Create an app-specific password. Never use the

read-only mode:

1. Export a minimal environment. For the first deployment, use Calendar

export ICLOUD_EMAIL='you@icloud.com'
export ICLOUD_PASSWORD='your-app-specific-password'
export ICLOUD_MCP_READ_ONLY=true
export ICLOUD_MCP_DEFAULT_TZ=Europe/Paris   # owner IANA zone; default UTC

Register the environment as env. The host can use YAML, JSON, TOML, a UI, or an orchestrator. The exact format depends on the host.

1. Register the absolute icloud-mcp path as the command in your MCP host.

Reload the host after environment changes.

1. Stdio carries JSON-RPC. stderr carries logs and the mutation audit.

This configuration exposes 7 tools: Calendar reads, local helpers, and icloud_capabilities. The process does not construct a Contacts or Mail client.

Optional domains (still host-agnostic export form):

# Contacts reads (writes also need ICLOUD_MCP_READ_ONLY=false)
export ICLOUD_MCP_ENABLE_CONTACTS=true

# Mail reads: IMAP identity may differ from ICLOUD_EMAIL (e.g. name@icloud.com)
export ICLOUD_MCP_ENABLE_MAIL=true
export ICLOUD_MAIL_ADDRESS='mailbox@icloud.com'
# export ICLOUD_MAIL_PASSWORD='...'   # optional; else copy of ICLOUD_PASSWORD

# Mail mutation (flags / move / trash); independent of send
export ICLOUD_MCP_ENABLE_MAIL_WRITE=true
export ICLOUD_MCP_READ_ONLY=false

# Mail send: requires exact recipient allowlist even under global read-only
export ICLOUD_MCP_ENABLE_MAIL_SEND=true
export ICLOUD_MCP_SMTP_ALLOWED_RECIPIENTS='alice@example.com,bob@example.net'

Shortened. The full README is on GitHub.