ICloud README

• 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).
• Every tool error is scrubbed before it reaches the agent: passwords and tokens masked, URLs cut to their host (iCloud DAV paths carry the account id), invisible characters removed. Health-check and unexpected errors, which may quote a server response, also drop account addresses and long numbers.
• 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.
• The admin API for the menu bar app is off unless ADMIN_PORT is set. It listens on 127.0.0.1 only, on its own port (never the public one or the tunnel), and every request needs the token in DATA_DIR/admin-token (mode 600); browser requests and non-loopback Host headers are refused.
• 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_messages 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_list_senders groups a folder by sender.
• Clean up in bulk, safely. mail_run_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_undo_bulk_action reverses it for 30 days. It needs at least one filter and never deletes permanently.
• Unsubscribe without following links. mail_unsubscribe_from_list 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_list_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.
• Who is waiting on whom. mail_list_awaiting_reply lists mail you sent to a person that has had no reply and no later message from them, in any folder, longest waiting first; mail_search_messages takes people_only (no newsletters), unanswered_only and since_hours.
• Layout checked, never rewritten. Send and draft results carry layout_warnings when a plain-text body has HTML tags, Windows line endings or one long paragraph.
• 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_move_event, calendar_delete_event, calendar_respond_to_event, calendar_create_calendar, calendar_update_calendar (rename), calendar_delete_calendar

• 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.
• Manage calendars. Create, rename and delete calendars. The default calendar is never deleted, and one that holds events is only deleted after a preview with a confirm token; iCloud.com can restore a deleted calendar for about 30 days. (iCloud ignores a color set this way, so there is no color option.)
• Move between calendars. calendar_move_event moves an event (a whole series, if it repeats) to another calendar with a WebDAV MOVE, so nothing is recreated and guests get no new invitation. Servers without MOVE get a copy first and the original deleted only after.
• Clashes and duplicates are reported. calendar_create_event returns the events a new one overlaps (conflicts, travel time counted on both sides, free, cancelled and declined events ignored) and a possible_duplicate with the same title and time; on_conflict / on_duplicate = refuse creates nothing instead.
• Invitations waiting for you. calendar_list_events(needs_reply=true) lists invitations you have not answered (to any of your addresses: add aliases to OWNER_ADDRESSES); starting_within_minutes looks from now.
• Answer invitations. calendar_respond_to_event 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_contact 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. add_attendees and remove_attendees change one person; a full 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, contacts_get_contact, contacts_list_birthdays, contacts_create_contact, contacts_update_contact, contacts_delete_contact, contacts_list_groups, contacts_get_group, contacts_create_group, contacts_update_group (rename, add or remove members), contacts_delete_group (the group only, never its members)

• 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_contacts 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_list_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. add_emails and add_phones add to a card without touching its existing addresses or their labels. Contact photos and notes are never returned.

reminders_list_lists, reminders_list_reminders, reminders_create_reminder, reminders_update_reminder, reminders_complete_reminder, reminders_move_reminder (the same reminder to another list, nothing deleted), reminders_delete_reminder (Reminders has no Recently Deleted, so this is final), reminders_create_list, reminders_update_list (rename), reminders_delete_list (with everything in it, only after a preview and its token)

• Runs through Apple's EventKit: every read is live and takes about 20 to 40 ms, however long your lists are. Active reminders by default; completed="only" lists what was done in a window, with when.
• Repeating reminders (repeat, daily or coarser: FREQ=WEEKLY;BYDAY=MO, FREQ=MONTHLY;BYMONTHDAY=1;COUNT=12) and extra alerts (alerts_minutes_before, alerts_at). Changing alerts keeps the alert at the due time itself.
• 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_list_folders, notes_list_notes, notes_read_note, notes_create_note, notes_append_to_note, notes_update_note, notes_create_folder, notes_move_note, notes_delete_note

• Read, create, edit and organise: add to a note (notes_append_to_note, keeps headings, lists and styling; notes with tables are refused) or rewrite it (notes_update_note, keeps the title), create folders and subfolders, and move notes between them.
• Edits are guarded. notes_read_note 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_folder, drive_search_files, drive_search_content, drive_get_info, drive_read_file, drive_get_file, drive_write_file, drive_create_folder, drive_move_item, drive_trash_item

• 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_file 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_file creates plain text files. Replacing a file needs overwrite, and the old version goes to the Trash. drive_move_item 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_item 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.

maps_get_travel_time, maps_search_places

• Travel time and distance between two places for walking, cycling, driving or public transport, for a departure or arrival time (public transport gives a time, not a route). Places are addresses, names or lat,lon; the destination is looked up near the origin, and the result names both resolved places so a wrong match is visible.
• With Maps on, calendar travel time uses a measured value when the owner has one and otherwise an Apple Maps estimate, always labelled as one; never an invented number. Repeat questions within 10 minutes are answered from a cache.
• Runs through MapKit on the Mac (bin/maps-cli, built by the installer). It needs no permission and never uses the Mac's own location. Turn it on with ENABLE_MAPS=true.

imessage_list_chats, imessage_read_chat, imessage_search_messages, imessage_send_message (off by default)

• Your own iMessage and SMS history on your Mac, read-only: conversations with who is in them (matched to your contacts), messages with reactions, delivery and read state and attachments by name, and search across the whole history (case and accents ignored).
• Only your own Messages database is read (the Mac user the helper runs as); another user on the Mac is never touched. The helper's Python needs Full Disk Access, the same grant iCloud Drive uses.
• Messages are other people's words: results carry the untrusted-data notice and safety warnings. IMESSAGE_HIDDEN_CHATS hides chats completely, service senders such as banks and one-time codes are hidden by default, IMESSAGE_MAX_AGE_DAYS limits how far back, and IMESSAGE_NEVER_SEND labels your own assistant's thread. Turn it on with ENABLE_IMESSAGE=true.
• Sending is off unless IMESSAGE_ALLOW_SEND=true, only reaches people on IMESSAGE_SEND_ALLOWLIST (empty means nobody), never reaches IMESSAGE_NEVER_SEND or the handles in the Mac's own imessage-never-send.txt, and by default waits for your approval on /outbox even when your mail sends directly. iMessage only, never SMS; each send is confirmed from what Messages records. The first send asks once for permission to control Messages: --selftest-imessage-send you@example.com on the Mac triggers that while you are there.

health_get_summary, health_get_day, health_get_status, health_refresh_data

• Daily figures from Apple Health: steps, active energy and distance (with how many hours had data), resting and walking heart rate, HRV, breathing rate, heart rate range, and every sleep with its stages, dated by the day it ended. health_get_day gives one day in detail (hourly totals, heart rate readings or the sleep timeline); health_get_status says how fresh the data is.
• A Mac cannot read HealthKit, so the data comes from your iPhone: a Shortcut writes the last two days to iCloud Drive (in the Shortcuts app's own folder, which the Drive tools cannot reach), and the Mac helper keeps it in a private store (health.sqlite, mode 600) and answers with figures, never the raw export. Build the shortcut with python3 mac-helper/health/build_shortcut.py health.shortcut, sign it with shortcuts sign --mode anyone, and run it from an automation such as opening an app you use often (a locked iPhone cannot read Health, so timed runs mostly fail). Each export overlaps the last two days, so one successful run fills any gap; overlapping exports never count twice.
• Your whole history comes from the Health app's own export (Profile, Export All Health Data): python3 health.py import export.zip on the Mac, in the helper's ops folder. It is read as a stream; where the iPhone and the Watch both counted the same steps, the larger total per hour counts, not the sum.
• A day or metric without data is left out rather than reported as zero, and the agent is told a gap means the Watch was off. The figures are marked private in every result. health_refresh_data runs a command you set up on the Mac only (health-refresh.json), never one the server sends. Turn it on with ENABLE_HEALTH=true.

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. icloud_get_helper_status says whether the Mac helper is online, when it was last seen, which version it runs, how many jobs are queued and how long they take. icloud_get_time gives the current date, weekday and time in your timezone, so an agent never books from a guessed date.

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, iCloud Drive, Maps, Messages and Health need the Mac helper and a Mac that is on; Health also needs your iPhone to export. 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.