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 names every capability. It takes a comma-separated list: calendar.read, calendar.write, calendar.delete, contacts.read, contacts.write, contacts.delete, mail.read, mail.mutate, mail.trash, mail.send, and mail.archive. Domain switches still enable a domain. Global read-only still removes every mutation and send. With no value, enabled domains are read-only. No switch, flag, or omission implies an effect. 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 authenticated read-only network 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 an offline profile check. It discovers collections and mailboxes outside MCP resource filtering, and it does not probe SMTP. See the diagnostic authorization limits. It is not available in v0.4.3. 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 gives an MCP host read-only Calendar access. 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.

Read-only by default. With no ICLOUD_MCP_PERMISSIONS, the server exposes reads only. Keep ICLOUD_MCP_READ_ONLY=true for the first run. No switch or omission grants an effect.

Choose an install path

The MCPB path is first because it needs no compiler. The missing evidence is a recorded install in a named host version, not a bundle defect. Until that record exists, this page does not claim that an MCPB host install was performed.

Path A: MCPB bundle (host installation unverified)

1. Download the bundle for your platform from the v0.5.2 release: linux-amd64, linux-arm64, or darwin-arm64.
2. Download icloud-mcp-v0.5.2-checksums.txt and the matching .sig and .pem files. Verify the bytes:

   shasum -a 256 -c icloud-mcp-v0.5.2-checksums.txt

cosign verify-blob \ --certificate icloud-mcp-v0.5.2-linux-amd64.mcpb.pem \ --signature icloud-mcp-v0.5.2-linux-amd64.mcpb.sig \ --certificate-identity "https://github.com/ThomasCrouzet/icloud-mcp/.github/workflows/ci.yml@refs/tags/v0.5.2" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ icloud-mcp-v0.5.2-linux-amd64.mcpb

1. Open the .mcpb file in your MCPB-capable host, or use that host's install command. The host reads manifest.json, asks for the declared user settings, and starts ${__dirname}/server/icloud-mcp.
2. Set email and the app-specific password. Keep read_only=true, permissions=calendar.read, enable_contacts=false, and enable_mail=false. Set your IANA default_timezone.
3. Start the connector and confirm exactly seven tools. Call icloud_capabilities and confirm readOnly is true.
4. Restart the host and confirm the settings survive. Uninstall by removing the bundle from the host, then revoke the app-specific password at Apple.

**Unverifie