# apple-icloud-mcp [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/chrischall/apple-icloud-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1277  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/apple-icloud-mcp

## Description
Unofficial: Apple Music, iCloud Calendar/Contacts/Mail, Apple Maps and WeatherKit, no Mac needed

## Tools
Capabilities this server exposes over MCP:

- **apple_healthcheck** — 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.
- **apple_music_search_catalog** — Search Apple Music's catalog by text for songs, albums, artists, playlists, music videos or stations. Results are grouped by type, each group with its own returned/hasMore/nextOffset, and carry catalog ids other tools take (e.g. to add songs to a playlist). Up to 25 per type per call. Needs an Apple Developer key (APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY) or web-player mode (APPLE_MUSIC_WEB_USER_TOKEN).
- **apple_music_get_catalog_items** — 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.
- **apple_music_get_charts** — 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.
- **apple_music_list_playlists** — 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).
- **apple_music_get_playlist** — 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.
- **apple_music_list_folders** — 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.
- **apple_music_search_library** — Search YOUR Apple Music library (not the whole catalog) by text for songs, albums, artists, playlists or music videos. Results are grouped by type with library ids (i.… songs, l.… albums, p.… playlists) and each group's returned/hasMore/nextOffset. Up to 25 per type. Needs APPLE_MUSIC_USER_TOKEN or web-player mode.
- **apple_music_list_library** — 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.
- **apple_music_get_history** — 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.
- **apple_music_get_recommendations** — 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_get_replay** — 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.
- **apple_music_get_ratings** — 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.
- **apple_calendar_list_calendars** — 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).
- **apple_calendar_list_events** — 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.
- **apple_calendar_search_events** — 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.
- **apple_calendar_get_event** — 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).
- **apple_calendar_find_free_time** — 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.
- **apple_contacts_search** — 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).
- **apple_contacts_get** — 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).
- **apple_contacts_list_groups** — 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).
- **apple_mail_list_mailboxes** — 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.
- **apple_mail_search** — 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.
- **apple_mail_get_message** — 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.
- **apple_mail_download_attachment** — 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.
- **apple_maps_geocode** — 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).
- **apple_maps_reverse_geocode** — 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).
- **apple_maps_search** — 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).
- **apple_maps_directions** — 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).
- **apple_maps_etas** — 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).
- **apple_maps_lookup_place** — 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).
- **apple_maps_snapshot_url** — 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.
- **apple_weather_get** — Weather forecast for a place from Apple Weather (WeatherKit): current conditions, hourly (up to 240 h), daily (up to 10 days), next-hour rain, severe-weather alerts (need countryCode). Returns temperature, feels-like, rain/snow chance and amount, wind, humidity, UV, sunrise/sunset. Takes latitude/longitude — use apple_maps_geocode first to turn a place name into coordinates. Days roll over in timeZone: pass the place's own zone when it differs from yours. Needs APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY and APPLE_WEATHERKIT_SERVICE_ID. Show the returned attribution with the data.
- **apple_weather_get_alert** — Get one severe-weather alert's full official text from Apple Weather (WeatherKit), unmodified, by its id (the alerts[].id from apple_weather_get called with countryCode). Returns the issuing agency (source), severity, effective/expiry times, detailsUrl and the messages verbatim. Apple serves an alert only while it is active; an expired one is NOT_FOUND. Needs APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY and APPLE_WEATHERKIT_SERVICE_ID.
- **apple_itunes_search** — 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.
- **apple_itunes_lookup** — 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.
- **apple_charts_get** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "apple-icloud-mcp": {
    "command": "npx",
    "args": ["-y","apple-icloud-mcp"],
    "env": {
      "ICLOUD_USERNAME": "",
      "ICLOUD_APP_PASSWORD": "",
      "ICLOUD_MAIL_ADDRESS": "",
      "DISPLAY_TZ": "",
      "APPLE_WRITE_MODE": ""
    }
  }
}
```

**Requires environment variables:** `ICLOUD_USERNAME`, `ICLOUD_APP_PASSWORD`, `ICLOUD_MAIL_ADDRESS`, `DISPLAY_TZ`, `APPLE_WRITE_MODE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What apple-icloud-mcp does

The apple-icloud-mcp MCP server exposes Apple web services to an MCP-compatible client. Its coverage includes Apple Music, iCloud Calendar, iCloud Contacts, iCloud Mail, Apple Maps, WeatherKit, and the iTunes Search API. The server is intended for access to the Apple accounts whose credentials are supplied; it does not provide access to other users' data.

Apple Music capabilities include catalog and library search, catalog lookups, charts, playlists, folders, listening history, recommendations, Replay data, ratings, favorites, and library changes such as creating playlists or adding tracks. Calendar tools can list, search, read, create, update, and delete events, including recurring events, and can identify free time within configurable working hours.

The README additionally documents iCloud Mail operations, Apple Maps geocoding and directions, WeatherKit forecasts and alerts, and iTunes searches and charts. Availability depends on the credentials and service configuration for each area.

## How it works

The apple-icloud-mcp MCP server uses Apple's network-facing services rather than macOS applications. Calendar access uses CalDAV, Contacts uses CardDAV, and Mail uses IMAP/SMTP. Apple Music uses its official API for catalog and account features; an optional web-player mode uses a browser session cookie for additional playlist-management operations. Apple Maps and WeatherKit use Apple developer services, while iTunes uses Apple's search and chart endpoints.

Requests run in the server process and operate on the Apple account associated with that process. Write operations have real effects: calendar invitations can send email, mail actions can send messages, and deleting playlists or contacts removes data. The project recommends running the health-check tool first because the implementation had not been verified against a live Apple account in the documented build environment.

## Setup and configuration

Node.js 22 or later is required. The package can be started with `npx -y apple-icloud-mcp`, installed from the Claude Desktop bundle, or built from source with npm. Claude Code can register it as an MCP server using the `claude mcp add` command. A source setup uses `npm install`, `npm run build`, and the provided environment-file template.

Calendar, Contacts, and Mail use an Apple ID plus an app-specific password. Set `ICLOUD_USERNAME` and `ICLOUD_APP_PASSWORD`; Mail may also require `ICLOUD_MAIL_ADDRESS` when the Apple ID is not an iCloud or me.com address. The normal Apple ID password is not accepted for these services, and changing the Apple ID password revokes existing app-specific passwords.

Apple Music's official API requires an Apple Developer key and Music User Token. Apple Maps requires an Apple Developer key. WeatherKit requires an Apple Developer key and Services ID. `DISPLAY_TZ` can configure the display time zone.

## Tools and capabilities

The documented tool set supports:

- Checking configured and reachable Apple services with `apple_healthcheck`.
- Searching, reading, and modifying Apple Music catalogs, libraries, playlists, folders, ratings, favorites, history, and recommendations.
- Listing, searching, creating, updating, deleting, and scheduling around iCloud Calendar events.
- Searching contacts, retrieving contact records, and listing contact groups.
- Using Apple Maps, WeatherKit, iCloud Mail, and iTunes features described by the project when their credentials are present.

## Limitations and notes

The project is unofficial and not affiliated with Apple. Apple terms govern use, and the README advises personal use, careful credential handling, and avoiding bulk extraction. Apple Music web-player mode is off by default and may be blocked because it relies on a private web API.

The codebase is described as AI-developed and not human-audited. Review the implementation and tool permissions before deployment. Service credentials are optional, but unavailable credentials disable the related service. Repeated failed sign-ins may lead to account lockout, and Apple rate limits may apply. The project also notes that write actions require confirmation and can be restricted through `APPLE_WRITE_MODE`.

_Full upstream README: https://allmcps.com/mcp/apple-icloud-mcp/readme_