icloud-mcp

icloud-mcp

iCloud Calendar, Contacts, and Mail through one stdio MCP server.

Get started | MCP tools | Configuration | Documentation

Connect an MCP host to iCloud with one Go binary. Calendar uses CalDAV; optional Contacts and Mail use CardDAV, IMAP, and SMTP. The host starts the process and exchanges JSON-RPC through stdin and stdout.

Why icloud-mcp?

Use this server when an MCP host needs to search calendars, find free time, or work with iCloud contacts and messages on a headless machine. It uses app-specific passwords and remote protocols, without macOS frameworks, browser automation, or private Apple APIs.

Capability gates let you start with Calendar reads and enable other operations as needed. Each domain has its own protocol clients and network policy. All enabled domains share one process: a process compromise can expose all loaded credentials. Use separate processes and account configurations for stronger isolation.

Privacy and security

Accounts: An Apple Account with iCloud Calendar and an app-specific password is required. Contacts uses the same identity. Optional Mail needs a full iCloud Mail address and can use a separate app-specific password. The server has no separate product account; the MCP host has its own account requirements.

Telemetry: The server has no telemetry or crash-reporting service. It writes operational logs and mutation audit records to stderr. The host controls log retention and has its own telemetry policy.

Data: Credentials are loaded at startup. Discovery state and keyed update results stay in process memory; the server writes no local data files. It sends authenticated requests to iCloud and returns account content to the MCP host. That host controls any further storage or transmission to a model provider.

• Fixed destinations. Calendar and Contacts use their iCloud hosts and validated shards on port 443. Mail uses imap.mail.me.com:993 and smtp.mail.me.com:587, with mandatory STARTTLS for SMTP. TLS 1.2 or later is required. DAV ignores proxy environment variables.
• Redaction and audit. The server redacts configured identities, passwords, and Basic/SASL forms from errors, results, and logs. Mutation audits contain domain, resourceType, and a process-local HMAC resourceToken, without raw resource paths, UIDs, mailboxes, or recipients.
• Host permissions. Remote text can contain prompt injection. A compromised host model can invoke every registered tool. Start with global read-only mode and enable only the capabilities you need.

See the threat model and reporting policy and security implementation.

Capability gates

ICLOUD_MCP_READ_ONLY=true removes every mutation and send tool from tools/list. It does not enable a disabled read domain. Contacts has no separate write flag. Mail mutation and send have independent gates. A send policy is required whenever the send flag is set, including under global read-only.

ICLOUD_MCP_RESOURCE_SCOPES optionally limits which calendars, address books, and mailboxes an agent may use. It is a semicolon-separated list of action=value[,value] entries. Actions are calendar.read, calendar.write, calendar.delete, contacts.read, contacts.write, contacts.delete, mail.read, mail.mutate, and mail.archive. A literal * keeps an action unrestricted.

Calendar values are paths. Contacts values are opaque identifiers or exact display names. Mail values are exact mailbox names. Omitted action scopes fall back to the read or write scope for that domain. Direct identifier injection is checked before the domain operation. Ambiguous or stale Contacts names fail closed. The variable is invalid if an action is unknown, duplicated, empty, or a Calendar path is malformed.

ICLOUD_MCP_PERMISSIONS optionally replaces the implicit write rules. It takes a comma-separated list: calendar.read, calendar.write, calendar.delete, contacts.read, contacts.write, contacts.delete, mail.read, mail.mutate, mail.trash, and mail.send. Domain switches still enable a domain. Global read-only still removes every mutation and send. With no value, the legacy switches above keep their documented behavior. For example, calendar.read,mail.read,mail.send gives Calendar reads and Mail send without Calendar, Contacts, or Mail mutation tools.

MCP tools

The server registers 10 tools by default, 7 with global read-only and optional domains off, and 24 with all gates on. Disabled tools are absent from discovery. The MCP interface provides tools over stdio.

The complete inventory lists all tools. Run icloud-mcp -doctor for concise read-only domain checks. Add -doctor-format=json for machine-readable output. The command validates local configuration, then probes enabled domains with a 10-second timeout each. It never creates, updates, moves, trashes, or sends. Exit status is 0 when every enabled domain is ready and 1 when a probe fails. Disabled domains stay disabled; enabled domains are never reported ready before a successful probe.

-doctor is not available in v0.4.3. It uses configured credentials and does not probe SMTP. For credential-free TLS checks and hosted-network limitations, see Mail network troubleshooting.

Representative read tools also publish output schemas and structuredContent. Their text content remains for older hosts. Both forms come from the same redacted values. Discover their argument schemas with the host's tool list. Domain failures set the MCP error flag and include a JSON code in text content. Follow the error and recovery reference.

Get started

This first run enables Calendar reads only. You need an MCP host, network access to iCloud, and an Apple Account with two-factor authentication to create an app-specific password. Never use the main Apple Account password.

Install the binary

With Go 1.26.0 or newer:

go install github.com/ThomasCrouzet/icloud-mcp/cmd/icloud-mcp@latestgo env GOPATH GOBIN

The executable is installed in GOBIN when set, otherwise in bin under GOPATH (normally $HOME/go/bin). Use its absolute path in the host config.

Without Go, use a release archive for Linux amd64/arm64 or macOS arm64. Archives include checksums, cosign signatures, and certificates. Follow the release verification procedure.

Prepare credentials

Store the Apple Account identity and app-specific password in separate files outside the repository. Each must be a regular file of at most 4 KiB, with mode 0600 or stricter. The host user must be able to read them. Use absolute file:// paths; the server reads these files only at startup.

Connect Claude Desktop

This example uses Claude Desktop on macOS. Open Settings > Developer > Edit Config. Its user configuration file is ~/Library/Application Support/Claude/claude_desktop_config.json; see the official local-server setup guide and environment configuration. Merge this entry into mcpServers, with your actual absolute paths:

{  "mcpServers": {    "icloud": {      "command": "/Users/you/go/bin/icloud-mcp",      "env": {        "ICLOUD_EMAIL": "file:///Users/you/.config/icloud-mcp/email",        "ICLOUD_PASSWORD": "file:///Users/you/.config/icloud-mcp/password",        "ICLOUD_MCP_READ_ONLY": "true",        "ICLOUD_MCP_DEFAULT_TZ": "Europe/Paris"      }    }  }}

Keep optional domains off for this run. Fully quit and reopen Claude Desktop. The host launches the binary. Calendar discovery starts on the first Calendar call, so a remote Calendar outage does not block Mail or Contacts startup. Open the host's connector tool list and confirm the icloud tools appear.

Run your first operation

Ask the host:

Call icloud_capabilities and confirm readOnly is true and toolCount is 7.Then call list_calendars with no arguments and show the calendar names.

The first call confirms capability discovery. The second reads iCloud. It returns count and a calendars array with name and path fields. An account with no calendars returns an empty array. A synthetic protocol fixture returns:

{  "count": 1,  "calendars": [    {"path": "/fixture/calendars/home/", "name": "Fixture Calendar"}  ]}

This output comes from the repository fixture, not a live account. Your names, paths, and count depend on your account. Next, ask the host to use search_events for the next seven days.

For another host, configure a custom stdio process with the same command and environment; its configuration format can differ. See host integration.

Configuration

The binary reads exactly 14 product environment variables from its process environment. It does not load .env files or host configuration files. .env.example lists the supported keys. The host or launching shell must supply them; restart the process after a change.

Boolean values accept unset, 0, false, 1, and true; the parser trims whitespace and ignores case. Invalid values fail before network access. Pass environment values as strings, including quoted booleans in YAML. Mail write or send without Mail is a boot error. Prefer exact recipient addresses: literal * permits any syntactically valid recipient and causes a boot warning.

For Calendar times, use an explicit RFC3339 offset or a local time without an offset in ICLOUD_MCP_DEFAULT_TZ. Do not label a local hour with Z. Timed results include an explicit numeric offset; all-day dates use YYYY-MM-DD. See the full configuration and date rules for log-level forms and optional-domain examples.

Operations

Use strong ETags for Calendar and Contacts updates and deletes. Creates use If-None-Match: *; updates and deletes use a strong If-Match. For creates, client_uid or its idempotency_key alias identifies the resource. For keyed updates, follow the cache contract and recovery procedure.

Limits

Tools have a 25 s deadline and DAV a 30 s HTTP timeout. Stdio frames are limited to 1 MiB and MCP results to 256 KiB. Calendar and Contacts each allow 60 reads and 20 writes per minute. Mail has separate limits of 60 reads, 20 mutations, and 20 sends per minute. See the public limits for search, parser, recurrence, and concurrency bounds.

Documentation

Build and test

From the repository root, use Go 1.26.0 or newer and Make. Build and test need no iCloud account or running service. CI and release builds pin Go 1.26.10.

make build        # bin/icloud-mcp, host Go; version defaults to devmake test         # go test ./... -race -covermake lint         # go vet and pinned golangci-lint v2.15.0

make release-all VERSION=vX.Y.Z packages Linux amd64/arm64 and macOS arm64 with the host toolchain. make release VERSION=vX.Y.Z uses a pinned Docker image for Linux arm64. Replace vX.Y.Z with a release version. Both require a clean worktree, including untracked files, and refuse to overwrite output. Tag releases build after CI and gitleaks pass. Live integration tests require credentials and explicit gates; see Testing.

Contributing

Follow CONTRIBUTING.md. Run gofmt, make test, and make lint before opening a pull request. Report bugs through GitHub Issues, with the version, enabled domains, reproduction steps, and redacted errors. Report vulnerabilities privately through SECURITY.md.

Status

The implemented scope is iCloud Calendar with optional Contacts and Mail.

Windows has no signed archive and no runtime support claim. Compilation is not evidence of file-credential handling, service startup, or installation.

Install without Go by downloading icloud-mcp-vX.Y.Z-<os>-<arch>.tar.gz and icloud-mcp-vX.Y.Z-checksums.txt from the release. Verify the checksum and cosign signature, extract icloud-mcp, and use its absolute path in the host configuration. See the release verification procedure.

Current limits to account for:

• Calendar. Recurring operations support a full series or one occurrence. this-and-future and RDATE are unsupported. A search range is at most 366 days.
• Contacts. Reads accept vCard 3.0 and 4.0. Writes support 3.0 only; vCard 4.0 and groups are read-only. Full-object updates preserve PHOTO and unknown fields.
• Mail. Message identity is (mailbox, UIDVALIDITY, UID). Reads return plain text and attachment metadata, without HTML or attachment bodies. move_message rejects SPECIAL-USE Trash and Junk destinations; use trash_message for intentional deletion. When CONDSTORE is advertised, set_message_flags requires expected_modseq. The adapter validates one UID STORE from the returned FETCH metadata, reports concurrent_modification for a stale MODSEQ, and never retries the write.
• Scope. Reminders, Notes, Photos, Drive, Find My, Keychain, Messages, and Home are outside the supported scope. Modern Reminders are not exposed by this CalDAV connector.

Architecture

[A stdio MCP client connects to capability gates and separate Calendar, Contacts, IMAP, and SMTP clients.]

Each domain keeps separate credentials, transports or dialers, rate limiters, and semaphores. Shared code handles redaction, audit, result bounds, and the process lifecycle. See the package map.

Direct dependencies

The single Go module has exactly 10 direct dependencies. Exact versions are in go.mod; required notices are in THIRD_PARTY_NOTICES.md.

License and credits

MIT. Copyright (c) 2026 Thomas Crouzet. See LICENSE and third-party notices.

Attribution

Calendar tool shape and several patterns were inspired by github.com/roygabriel/mcp-icloud-calendar (MIT, copyright 2026 Gabe). Code was rewritten, not copied.