icloud-mcp-server 0.4.0

• iCloud credentials exist only in the server environment or the macOS Keychain. Clients hold short-lived bearer tokens for this server.
• Clients may register dynamically, but nothing is authorised without the owner password. Redirect hosts are restricted. Tokens are stored as SHA-256 hashes (file mode 600). The approval and outbox pages lock after 10 wrong passwords in 15 minutes (server-wide; existing tokens keep working).
• Every refused sign-in renewal is logged with its reason (already rotated, expired, wrong client, not recognised), never with token values, and unauthenticated callers cannot flood the log: docker compose logs icloud-mcp | grep 'oauth:'.
• Text from mail, events, notes and files is stripped of invisible steering characters (Unicode tag characters, zero-width spaces, direction overrides; the marks Kurdish, Persian and Arabic text need are kept), and results carry safety_warnings when the text addresses an AI, asks for passwords or codes, or says bank details changed (English and Dutch).
• Health-check errors are redacted: no passwords, account addresses or account ids.
• The MCP endpoint validates Host and Origin. Tool results carry an untrusted-content notice. HTTP-client request logging is disabled so account identifiers do not reach the logs.
• The Mac bridge runs on its own private TLS port with a self-signed certificate the helper pins by fingerprint, plus a bearer token. It is never served on the public address or through the tunnel. The server sends only an operation name and validated arguments from a fixed list, never script text.
• Single-owner by design: one deployment serves one iCloud account. It is not multi-tenant, and storing other people's app-specific passwords is deliberately out of scope.

• Replies keep the Re: subject, In-Reply-To and References, the right recipients and the quoted original in plain text and HTML. Sent mail is copied to Sent and the original is flagged Answered (forwards get $Forwarded). draft=true saves to Drafts instead of sending.
• mail_get_messages reads a batch (a day's unread mail, a whole thread) in one IMAP round trip, about 7 times faster than one at a time.
• Search every folder at once. mail_search with all_folders=true looks in Archive, Sent, Junk and your own folders too, newest first, because mail rules and replies file messages away from the inbox.
• Newsletters are told apart from people. Search results mark bulk mail (a List-Unsubscribe or List-Id header, bulk precedence, automated or no-reply senders) and say how it can be unsubscribed from; mail_senders groups a folder by sender.
• Clean up in bulk, safely. mail_bulk_action (move, archive, trash, mark read) always previews first: the count, a sample and a confirm token that stands for exactly those messages. Running needs that token, so mail that arrived since is never touched. Every run is logged by Message-ID and mail_bulk_undo reverses it for 30 days. It needs at least one filter and never deletes permanently.
• Unsubscribe without following links. mail_unsubscribe uses only the List-Unsubscribe header: the standard one-click request (RFC 8058, HTTPS to public addresses only) or an unsubscribe email through the normal send path, so approval rules apply. Links in the body are never followed, unsubscribe web pages are only handed to you, and mail in Junk is refused.
• Bookings come out exact. mail_extract_bookings reads the schema.org booking data airlines, hotels, rail and ticket shops embed (flights, stays, trains, buses, rental cars, restaurants, events) and .ics invitations, and returns each with a ready calendar_create_event block. Nothing is guessed from the wording; a message without that data says so.
• Only what changed. mail_changes returns a token; passed back next time, it lists just the new messages and those whose read, flagged or answered state changed, using IMAP CONDSTORE instead of re-reading the folder. If iCloud renumbered the folder, it says to start over rather than guess.
• Stale ids are refused. Every message comes with its folder's uidvalidity; tools that act on a uid accept it back and refuse if iCloud has renumbered the folder since, instead of touching a different message.
• Reading a message does not mark it read. Bcc recipients receive the mail, but the header is stripped on the wire.
• Recipients accept a@b.com, Name <a@b.com> or mailto:a@b.com. Anything else is rejected with a clear error and never silently dropped.

calendar_list_calendars, calendar_list_events, calendar_find_free_time, calendar_get_event, calendar_create_event, calendar_update_event, calendar_delete_event, calendar_rsvp

• Multiple calendars, recurring events expanded when listing, all-day events, alerts, links, notes and attendees. Editing or deleting a recurring event changes the whole series, or just one date when you pass occurrence_start (the rest of the series is left alone).
• Finding free time is one call. calendar_find_free_time returns openings of a given length within your hours and chosen weekdays. Travel time counts as busy; events marked free, cancelled events and invitations you declined do not; all-day events are listed separately instead of guessed about.
• Know whether an invitation went out. After inviting people, the result reports what iCloud recorded for each guest (sent, delivered, or refused, for example a mistyped address), so an agent never claims someone was invited when they were not.
• Answer invitations. calendar_rsvp accepts, declines or marks tentative, for the whole series or one date; iCloud emails the organizer itself.
• Safe to retry. calendar_create_event and contacts_create take an optional request_id: if a call times out and is retried with the same one, the first attempt is found instead of creating a duplicate.
• Apple travel time and map locations. Events can carry Apple's travel time (by bike, on foot, by car or public transport) and a structured destination, which is what makes Apple draw the map card.
• Adding a guest leaves everyone else alone. Updating the guest list merges instead of replacing, so existing guests keep their RSVP and aren't sent the invitation again. Invitations are emailed by iCloud itself and are off unless you allow them.

contacts_search, contacts_get, contacts_upcoming_birthdays, contacts_create, contacts_update, contacts_delete

• Contacts are fetched whole, cached and searched locally by name, nickname, company, email or phone, ignoring accents. A contact with no email comes back with has_email: false, so an agent asks instead of guessing.
• Misspelled names are handled. contacts_search suggests similar-sounding names when nothing matches exactly, and mail_find_correspondent finds people you've emailed by approximate name, address or company, reading only message headers. Approximate matches are labelled, and agents must ask you to confirm before sending, inviting or editing on one.
• Postal addresses are read and written as street, city, region, postcode and country, with home, work or your own labels ("Holiday house"), stored the way Apple's Contacts app expects.
• Birthdays coming up. contacts_upcoming_birthdays lists them soonest first, with the age turned when the year is known (Apple's "year unknown" 1604 is understood, and 29 February falls on the 28th in other years).
• Updates keep every field outside the changed ones and use ETags to refuse stale overwrites. Contact photos and notes are never returned.

reminders_lists, reminders_list, reminders_create, reminders_update, reminders_complete, reminders_delete

• Runs through Apple's EventKit: every read is live and takes about 20 to 40 ms, however long your lists are. Only active reminders are returned.
• List names can repeat across accounts, so tools accept a list_id and refuse an ambiguous name. Due dates are validated as real dates (a bare date means 09:00 local time).

notes_folders, notes_list, notes_read, notes_create, notes_append, notes_update, notes_create_folder, notes_move, notes_delete

• Read, create, edit and organise: add to a note (notes_append, keeps headings, lists and styling; notes with tables are refused) or rewrite it (notes_update, keeps the title), create folders and subfolders, and move notes between them.
• Edits are guarded. notes_read returns a content_hash; append and update need it with the current title, so a note that changed since it was read is never overwritten. Locked notes, notes with attachments and notes in Recently Deleted are refused, and the old version is saved to ~/Library/Application Support/icloud-mac-helper/note-backups/ before anything is written.
• Move and delete act on one note at a time and need its current title as well as its id, so a stale or wrong id changes nothing.
• Delete moves a note to Recently Deleted, where you can recover it for about 30 days. It refuses locked notes, and notes already in Recently Deleted, because removing them from there would be permanent. Nothing is ever moved into Recently Deleted.

drive_list, drive_search, drive_search_content, drive_info, drive_read, drive_get_file, drive_write, drive_create_folder, drive_move, drive_trash

• Works on your whole iCloud Drive as your Mac keeps it in sync, so every change syncs to your other devices by itself.
• drive_read returns text from plain text files, PDFs and Word, RTF, ODT and HTML documents. Files offloaded by "Optimise Mac Storage" are downloaded first. If that takes too long, the answer says the file is still downloading, instead of timing out.
• Search inside files. drive_search_content finds words in the text of plain text, PDF, Word, RTF, ODT and HTML files (case and accents ignored) and returns an excerpt for each match. Each file is read once and its text kept in a private cache on the Mac (drive-text-cache.sqlite, mode 600), so later searches are fast and still work after macOS offloads the file. Files that are only in iCloud are skipped unless download=true, and the answer always says how many were left out. (Spotlight was tried first and dropped: its index of iCloud Drive was measurably incomplete.)
• drive_write creates plain text files. Replacing a file needs overwrite, and the old version goes to the Trash. drive_move never overwrites.
• drive_get_file hands over the file itself (base64, up to MAX_ATTACHMENT_BYTES), so an agent can attach it or send it on, the way mail_get_attachment does for mail.
• Nothing is ever deleted permanently. drive_trash moves items to the Trash, where you can recover them.
• Paths are relative to the Drive and can't leave it, not through .. and not through a symbolic link (links that lead outside are not even listed). The Drive's trash folder is off limits.

icloud_check_health checks every enabled area in one call (signs in to mail, lists calendars, reads the address book, asks whether the Mac helper is online) and says how long each took. mac_helper_status says whether the Mac helper is online, when it was last seen and which version it runs.

These only show up against Apple's real servers, never against local test servers:

• CalDAV rejects UID-filtered queries (412), so events are fetched by resource name with a scan fallback. An attendee who is the account owner is rewritten to an internal path with the address in the EMAIL parameter.
• IMAP has no MOVE. Moving and deleting use COPY, flag \Deleted, then UID EXPUNGE of exactly those messages (never a plain EXPUNGE). iCloud doesn't file sent mail by itself.
• CardDAV discovery ends on a different host than it starts on (follow the returned links), returns the whole address book in one request, and stores about half of all emails in grouped itemN.EMAIL properties with labels in itemN.X-ABLabel.
• Travel time is a number Apple stores, not a live estimate. It is never recomputed, so an origin or travel mode without a duration is refused instead of silently doing nothing.

• Reminders, Notes and iCloud Drive need the Mac helper and a Mac that is on. Contact photos and notes are deliberately not exposed to agents, and deleting a contact is permanent.
• One identity: aliases can't be used as the From address. Attachments that aren't text come back as base64 and are size-capped.
• Mail calls reuse up to two logged-in connections, which saves the login (about a second) on each call after the first; calendar and contacts calls take about 1.5 to 5 seconds against iCloud.
• Claude doesn't show custom icons for custom connectors yet (open request). The server serves and advertises the project logo anyway, so clients that do show icons, and your browser tab on the approval and outbox pages, display it.

python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
pytest tests --ignore=tests/integration      # offline tests, no network
sudo apt install dovecot-imapd && dev/start_local_stack.sh
pytest tests                                 # adds integration tests against local Dovecot, an SMTP sink and Radicale
python packaging/mcpb/build.py               # builds the Claude Desktop extension into dist/
python dev/readme_art.py                     # redraws the README artwork in assets/readme/

dev/e2e_http.py drives a running server over HTTP (OAuth plus tool calls). Local test servers accept things iCloud doesn't (see the quirks above), so treat selftest and a manual run against a real account as part of testing any change.