icloud-mcp

Remote protocols only(CalDAV, CardDAV, IMAP, SMTP with app-specific passwords). Not macOS EventKit, AppleScript, browser automation, or a private Apple API. Runs headless on Linux and macOS; pure Go also builds for Windows (CI smoke-buildswindows/amd64; GitHub Release archives ship linux/amd64, linux/arm64, and darwin/arm64). Suitable for agents and orchestration, not only a desktop chat app.

Host-agnostic.Any MCP client that can spawn a child with an environment and wire stdin/stdout works: personal agents, Hermes, OpenClaw, IDE bridges, runners, or other stdio hosts. No preferred model vendor, chat product, or reseller. Configuration is the process environment only; the binary does not parse host-specific config files or.env.

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

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

- Registercommand= absolute path toicloud-mcpand thisenvin your MCP host (YAML, JSON, TOML, UI, or orchestrator; format is host-specific).
- Stdio = JSON-RPC;stderr= logs and mutation audit. Reload the host after env changes.

With that config the process exposes7 tools(Calendar reads + local helpers +icloud_capabilities). No Contacts or Mail client is constructed.

Optional domains (still host-agnosticexportform):

# 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'

Boot-onlyfile://secrets (regular files only, at most 4 KiB, mode 0600 or stricter; never re-read after start):

export ICLOUD_EMAIL='file:///run/secrets/icloud-email' export ICLOUD_PASSWORD='file:///run/secrets/icloud-password' export ICLOUD_MAIL_ADDRESS='file:///run/secrets/icloud-mail-address' export ICLOUD_MAIL_PASSWORD='file:///run/secrets/icloud-mail-password'

Maximum23tools. Disabled tools are absent fromtools/list; disabled domain clients are not constructed.

ICLOUD_MCP_READ_ONLY=trueremoves every Calendar/Contacts write, every Mail mutation, and Mail send. It does not enable a disabled read domain.

Exactly12product environment variables:

Booleans accept only unset,0,false,1, ortrue. Invalid values fail at boot. Config is validatedbeforeany network access: Mail write/send without Mail, Mail without address/password, or send without recipient policy are boot errors (including under read-only for the send policy). Global read-only can coexist with write/send flags but suppresses their registration.

Log levels are trimmed and case-insensitive:debug/-4,info,warn/warning/2, anderror/4. Unset or unrecognized values useinfo.

Flags:-version; optional-health 127.0.0.1:port(loopback-only/healthzand/statusJSON with domains and rate limits); optional-audit-format=json|text(defaultjsonmutation audit on stderr).

- Calendarinputstart/end: RFC3339 with offset, or wall clock without offset inICLOUD_MCP_DEFAULT_TZ. Prefer no-offset for the user's local time. Recurring or explicit-timezone creates write TZID + VTIMEZONE; non-recurring timed defaults to UTCZon the wire. All-day usesVALUE=DATE.
- Calendaroutput: timed events always use RFC3339 with an explicit numeric offset inICLOUD_MCP_DEFAULT_TZ(never bareZ). All-day dates areYYYY-MM-DD. Seecalendar_capabilities.outputFormat.
- Contacts birthdays: writeYYYY-MM-DDonly.
- Mail search:sinceinclusive,beforeexclusive (YYYY-MM-DD).

Untrusted remote text can influence an LLM on the host; labels are not a boundary. A compromised model can call everyregisteredtool. Same model for every host and vendor.