io.github.chrischall/apple-icloud-mcp

Create an iCloud Calendar event: title, startDate/endDate (timed default 1 hour; all-day endDate = last day), location, notes, url, alarms, recurrence, attendees. Goes into calendar, else ICLOUD_DEFAULT_CALENDAR, else the first writable calendar not shared with others; a shared one is named (APPLE_WRITE_MODE=additive refuses it, and attendees). With attendees it asks first (iCloud emails them): a prompt where the client supports one, else the first call performs NO write and returns a preview plus a confirmToken for a repeat call (MCP_CONFIRM_MODE). Without attendees the first call creates the event immediately.

Delete an iCloud Calendar event. Recurring: span thisEvent (default; the one occurrence an "#occ=" id names), futureEvents (it and all later ones) or allEvents (the whole series). Calendar has no trash. If the event has attendees iCloud emails them a cancellation. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call performs NO write and returns a preview of exactly what would happen plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Find free time in your iCloud calendars: open slots per day within working hours (workdayStart/workdayEnd, default 09:00–17:00, weekdays only by default) at least minDurationMinutes long (default 30). Busy = events not marked free, not cancelled and not declined by you; all-day events block only with includeAllDay (then even marked free). Nothing before now is offered. Window max 31 days. Dates are ISO-8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS], optional Z or ±HH:MM. An offset-less time is wall clock in timeZone (default DISPLAY_TZ), never UTC; a stored floating one is read in DISPLAY_TZ.

Get one iCloud Calendar event in full (notes untruncated, attendees, alerts, recurrence rule in plain English) by the id list/search returned. An id ending in "#occ=…" is that one occurrence; a bare recurring id describes the series. includeIcs adds the raw iCalendar (lines unfolded, account ids redacted).

List your iCloud calendars (event calendars only): id, name, color, whether you can add events to it, whether it is shared (shared: with you by someone else; sharedByYou: by you with others), and which one new events go into by default. Use the name or id with the other apple_calendar_* tools. Needs ICLOUD_USERNAME and ICLOUD_APP_PASSWORD (an app-specific password).

List iCloud Calendar events (appointments, meetings) in a date window, recurring events expanded into occurrences, sorted by start. Window: fromDate (default today) + toDate (exclusive) or daysAhead (default 7), max 366 days; the window is always stated. Filter by calendars; page with limit/offset (totalMatched, nextOffset). Rows are compact by default (see view). Each event has an id for get/update/delete. Dates are ISO-8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS], optional Z or ±HH:MM. An offset-less time is wall clock in timeZone (default DISPLAY_TZ), never UTC; a stored floating one is read in DISPLAY_TZ.

Search iCloud Calendar events by text (case-insensitive match in title, location or notes) within a date window: fromDate (default today; may be in the past) + toDate or daysAhead (default 30), max 366 days. Only that window is searched, and the response says so. Returns matching occurrences sorted by start, with ids; rows are compact by default (see view). Dates are ISO-8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS], optional Z or ±HH:MM. An offset-less time is wall clock in timeZone (default DISPLAY_TZ), never UTC; a stored floating one is read in DISPLAY_TZ.

Change an iCloud Calendar event: title, startDate/endDate, isAllDay, location, notes, url ("" clears), alarms, attendees (full new list), calendar (moves it). Recurring: span thisEvent (default, "#occ=" id), futureEvents (splits the series) or allEvents. Returns before/after. If the event has or gets attendees it asks first (iCloud emails them): a prompt where the client supports one, else the first call performs NO write and returns a preview plus a confirmToken for a repeat call (MCP_CONFIRM_MODE). Without attendees the first call changes the event immediately.

Apple's current top charts (no Apple account or key): most-played songs, albums, music videos and playlists on Apple Music; top podcasts, trending podcast episodes and top subscriber channels; top free/paid apps and books; top audiobooks. Returns ranked entries (rank, id, name, artist, release date, genres, store link) for one storefront (two-letter country code; default APPLE_MUSIC_STOREFRONT, else us), up to the top 100. Song, album and podcast ids work with apple_itunes_lookup and Apple Music.

Create a new contact in iCloud Contacts. Needs a givenName, familyName or organization; optional middleName, nickname, department, jobTitle, note, birthday (YYYY-MM-DD, or --MM-DD without a year), and lists of emails, phones, urls and postal addresses, each with an optional label (home, work, mobile, other or custom text). Returns the new contact's id and details as re-read from iCloud (verified). Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password). Available when APPLE_WRITE_MODE is additive or all.

Permanently delete one contact from iCloud Contacts (on every device) by id. The preview shows its name, organization, emails and phones. Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password). Needs APPLE_WRITE_MODE=all. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call performs NO write and returns a preview of exactly what would happen plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Get one iCloud contact in full by id (from apple_contacts_search): names, organization, job title, emails, phones, postal addresses and URLs — each with its label and an entryId that apple_contacts_update can target — birthday, note, the contact groups it belongs to, whether it has a photo, and when it was last modified. Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password).

List the contact groups in iCloud Contacts (e.g. Family, Work): each group's id, name and member count. Pass a group name to apple_contacts_search to list its members. Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password).

Search the user's iCloud Contacts (address book) by name, nickname, company, job title, email, or phone number digits — optionally only within one contact group. Omit query to list everyone. Returns the total number of matches and a page of rows sorted by name: id, name, organization, job title, emails and phones with labels. Use apple_contacts_get with an id for addresses, birthday, note and entryIds. Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password).

Edit an existing iCloud contact in place. Scalar fields (givenName, familyName, middleName, nickname, organization, department, jobTitle, note, birthday) replace the current value; "" clears it. emails/phones/urls/addresses take change objects {action: add|remove|replace} aimed at one entry by entryId (from apple_contacts_get) or current value; an absent target is a reported no-op listing what is there. The rest of the card is kept byte-for-byte. Returns before/after, re-read to verify. Requires ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (an app-specific password). Needs APPLE_WRITE_MODE=all.

Check which Apple services (Apple Music, iCloud Calendar, Contacts, Mail, Apple Maps, WeatherKit, iTunes) are configured and reachable. For each: whether credentials are set (and which variables to set if not), and whether Apple accepted them on a cheap read-only request. Also reports the write mode and display time zone. Run this first when a tool fails or to see what this server can do.

Look up iTunes Store items (no Apple account or key) by ids — 1–200 trackId/collectionId/artistId values, e.g. from apple_itunes_search or an Apple Music link — or by one UPC/EAN (album), ISBN (book) or bundleId (app). With one item and entity, lists its related items: an album's songs (song), an artist's albums (album), a podcast's episodes (podcastEpisode, newest first; Apple serves at most 200 and fewer for some shows). Ids match Apple Music catalog ids; ids not found are listed. Episode ids cannot be looked up directly.

Search Apple's iTunes Store catalog — songs, albums, artists, podcasts and podcast episodes, audiobooks, apps and ebooks — with no Apple account or key. Returns ids, names, artist, release date, duration and store links. trackId/collectionId/artistId are the SAME ids Apple Music's catalog uses (handy for adding songs to playlists); podcasts include feedUrl. Narrow with media, entity and attribute; country picks the store (default APPLE_MUSIC_STOREFRONT, else us). Apple serves only the top 200 matches; it allows about 20 searches a minute.

Download one attachment from an iCloud Mail message as an embedded binary resource. Use the 1-based index shown by apple_mail_get_message. Reads the message without marking it read. Defaults to a 10 MiB attachment limit (maximum 20 MiB). Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

Read one iCloud Mail message by uid (from apple_mail_search): headers (from, to, cc, reply-to, date, subject, message-id), the body as plain text (HTML converted to readable text when there is no text part), a truncated flag, and attachment names/types/sizes (no attachment contents). Never marks the message read; to do that, use apple_mail_update_flags with seen:true. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

List the iCloud Mail mailboxes (folders): path, name, special use (inbox, sent, drafts, trash, junk, archive) and, by default, message and unread counts. Use the path (or an alias) as `mailbox` in the other apple_mail_* tools. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

Move iCloud Mail messages (1–100 uids from apple_mail_search, one mailbox) to another mailbox: a path from apple_mail_list_mailboxes or an alias (inbox, archive, trash, junk, sent, drafts). Moving to trash is recoverable from Deleted Messages. Returns the new uids and verifies the messages left the source. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

Search emails in one iCloud Mail mailbox (default INBOX) by sender, recipient, subject, full text, received date range, unread and flagged state. Returns newest first with paging (total, nextOffset) and, per message: uid, date, from, replyTo (when it differs from from; confirm which to answer), to, cc, subject, seen, flagged, hasAttachments, size. Criteria combine with AND. Reading results never marks mail read. Use the uid with apple_mail_get_message. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

Send a plain-text email from your iCloud Mail address (to/cc/bcc, subject, body; no attachments). Body ≤ 20,000 chars, all shown for confirmation. inReplyTo {mailbox, uid} threads a reply ("Re:" subject; quoteOriginal quotes it), warning if the original's Reply-To is not a recipient. Saved to Sent. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call performs NO write and returns a preview of exactly what would happen plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Mark iCloud Mail messages read or unread, and flag or unflag them, by uid (1–100 uids from apple_mail_search, one mailbox). Only messages not already in the requested state are changed; the result is re-read to verify and lists each message's state and any uids that were not found. Needs ICLOUD_USERNAME + ICLOUD_APP_PASSWORD (app-specific password), and ICLOUD_MAIL_ADDRESS unless the Apple ID is an @icloud.com/@me.com/@mac.com address.

Driving, walking or cycling directions between two places with Apple Maps (addresses or "lat,lng"). Traffic-aware travel time for now or a given departure/arrival time. Returns each route's distance (mi and km), duration, tolls, estimated arrival (or leave-by time) and turn-by-turn steps; view "full" adds route geometry. Options: avoid tolls (a preference, not a guarantee), alternate routes. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Travel time and distance from one point to up to 10 destinations at once with Apple Maps — driving with live traffic, transit, walking or cycling (e.g. "which of these stores is closest by car?"). Coordinates only ("lat,lng"): geocode addresses first with apple_maps_geocode. Returns per destination: distance, travel time with and without traffic, and estimated arrival. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Turn an address or place name into coordinates with Apple Maps (geocoding). Returns matching places with latitude/longitude, a one-line address, country code and a place id (for apple_maps_lookup_place). Use it first when a tool needs coordinates (apple_maps_etas, apple_weather_get). Optional: limit to countries, bias toward a nearby point, response language. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Look up Apple Maps places by place id — the id field from apple_maps_search, apple_maps_geocode or apple_maps_reverse_geocode results — 1 to 50 at once. Returns each place's name, category, coordinates, address, phone and website; ids Apple could not resolve are listed with the reason. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Find the street address at a latitude/longitude with Apple Maps (reverse geocoding) — e.g. "where is 37.33,-122.01?". Returns the place(s) at that point: one-line address, name, country code and place id. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Search Apple Maps for places: businesses, points of interest, addresses, landmarks (e.g. "coffee", "EV charger", "Golden Gate Bridge"). Bias toward a point with near; filter by Apple POI category (Restaurant, Cafe, GasStation, EVCharger, Hotel, Parking, Pharmacy…), result type or country. Returns places (name, category, coordinates, address, phone, website, place id) and nextPageToken for the next page. Needs an Apple Developer key with MapKit JS enabled: APPLE_TEAM_ID + APPLE_KEY_ID + APPLE_PRIVATE_KEY (or APPLE_MAPS_KEY_ID / APPLE_MAPS_PRIVATE_KEY).

Make a signed link to a static Apple Maps image (PNG): centred on an address or "lat,lng", and/or with pins (each with an optional label, colour and one-character glyph; the map fits the pins when no center is given). Choose zoom, size (up to 640x640), scale, map type (standard, hybrid, satellite, mutedStandard) and light/dark. Returns the URL only — nothing is downloaded; the link can be made to expire. Uses the same Apple Developer key (MapKit JS): APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY.

Mark catalog songs, albums, playlists, artists or music videos as favorites (the star in Apple Music; favorite songs go to your Favorite Songs playlist), by catalog id, up to 100 per type. Apple answers only "accepted" and silently ignores ids it cannot favorite. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Append songs (up to 500 catalog or library ids) to the end of one of your library playlists. By default skips songs already in the playlist (matched by catalog id; refused while Apple does not show your last change to it yet). Refuses playlists you cannot edit (Apple-curated or collaborative). Verifies the new tracks show. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Add catalog songs, albums, playlists or music videos to your Apple Music library by catalog id (up to 100 per type). Apple answers only "accepted": it silently ignores ids it cannot add and new items can take a while to appear, so check later with apple_music_search_library. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Create a playlist folder in your Apple Music library, at the top level or inside another folder. Returns the new folder id (p.…) for apple_music_create_playlist / apple_music_move_playlist. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Create a new playlist in your Apple Music library, optionally with tracks (up to 500 catalog or library song ids; added 100 at a time), a description, a folder and public visibility (not in APPLE_WRITE_MODE=additive). Returns the new playlist id (p.…) and checks it by re-reading (Apple can take a few seconds to show it). Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Delete one of your library playlists (songs stay in your library). For an Apple playlist saved to your library, this removes it from your library. The preview shows its name, track count and date added; verifies it is gone. Uses Apple's web-player API (unofficial; needs APPLE_MUSIC_WEB_USER_TOKEN). Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call performs NO write and returns a preview of exactly what would happen plus a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Look up Apple Music catalog songs, albums, artists, playlists, music videos or stations by id — or songs/music videos by ISRC, albums by UPC. A single album or playlist also returns its track list (paged); a single artist can include views such as top-songs or latest-release. Reports ids Apple did not return. Needs an Apple Developer key or web-player mode.

Get Apple Music's top charts (most played songs, albums, playlists, music videos) for a storefront, optionally for one genre. Each chart has its own returned/hasMore/nextOffset and ranked items with catalog ids. Needs an Apple Developer key or web-player mode.

Your recent Apple Music listening: recently-played (albums, playlists, stations), recently-played-tracks (songs), recent-stations, or heavy-rotation. Apple gives no play timestamps or counts here and pages recently-played 10 at a time and tracks 30 at a time (this tool pages for you; only about the last 50 items are reachable). Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Read one playlist — a library playlist (p.…) or a catalog playlist (pl.…) — with its tracks in order. Each track has its 1-based position, library id, catalogId, name, artist, album and duration. Paged (up to 300 per call), or allTracks for the whole list (up to 5000); a complete read returns a revision (for reorder/remove tracks' expectedRevision). Library playlists need APPLE_MUSIC_USER_TOKEN or web-player mode.

Whether you have loved or disliked songs, albums, playlists, music videos or stations — catalog or library ids — returning love, dislike or none per id. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Your personal Apple Music recommendations ("Made for You", "Recently Played" and similar groups), each with its title and the albums, playlists or stations in it (catalog ids). Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

Apple Music Replay: your top songs, albums and artists for the latest Replay year, or for a given year (with play counts where Apple provides them). Needs APPLE_MUSIC_USER_TOKEN or web-player mode; a specific year uses an undocumented Apple endpoint that works most reliably in web-player mode.

List the playlist folders in your Apple Music library: the top level, or the sub-folders of one folder. Each has its folder id (p.…, for apple_music_list_playlists folderId, apple_music_create_folder parentFolderId and apple_music_move_playlist), name and dateAdded, plus how many playlists sit directly in the folder. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

List what is in your Apple Music library: all songs, albums, artists or music videos (alphabetical, paged), or recently-added items. Items carry library ids and, for songs, the catalogId. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.

List the playlists in your Apple Music library (alphabetical), or the contents of one playlist folder (folders and playlists). Each has its library id (p.…), name, description, canEdit, isPublic, hasCatalog, dateAdded and lastModifiedDate. Paged. Needs APPLE_MUSIC_USER_TOKEN with an Apple Developer key, or web-player mode (APPLE_MUSIC_WEB_USER_TOKEN).