Skip to content
MCP server

Apple Icloud MCP

Unofficial MCP server for Apple Music, iCloud mail, calendar, contacts, Maps and weather

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI
Runs
Locally
Version
0.5.0
Listing updated
today

Similar MCP servers

About Apple Icloud MCP

Apple Icloud MCP is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.

This server reaches Apple's web services from any operating system, so it runs on Linux, Windows or a container as well as a Mac. Each service switches on only when its credentials are present, and apple_healthcheck reports which ones work.

What each needs differs. Apple Music through the official API needs an Apple Developer key plus a Music User Token. An opt-in web-player mode uses a music.apple.com cookie and unlocks rename, delete and reorder. iCloud Calendar, Contacts and Mail use an Apple ID with an app-specific password over CalDAV, CardDAV and IMAP/SMTP. Apple Maps and WeatherKit use a developer key, and iTunes Search needs nothing.

The README is blunt about risk: it is unofficial, built entirely by Claude Code with no human audit, and not yet verified against a live Apple account. Writes are real, so sending mail or deleting a playlist asks for confirmation first, and APPLE_WRITE_MODE can remove write tools entirely.

Install

Run in a terminal

claude mcp add apple-icloud-mcp --env APPLE_PRIVATE_KEY='<APPLE_PRIVATE_KEY>' --env APPLE_MUSIC_PRIVATE_KEY='<APPLE_MUSIC_PRIVATE_KEY>' --env APPLE_MAPS_PRIVATE_KEY='<APPLE_MAPS_PRIVATE_KEY>' --env APPLE_WEATHERKIT_PRIVATE_KEY='<APPLE_WEATHERKIT_PRIVATE_KEY>' --env APPLE_MUSIC_DEVELOPER_TOKEN='<APPLE_MUSIC_DEVELOPER_TOKEN>' --env APPLE_MUSIC_USER_TOKEN='<APPLE_MUSIC_USER_TOKEN>' --env APPLE_MUSIC_WEB_USER_TOKEN='<APPLE_MUSIC_WEB_USER_TOKEN>' --env APPLE_MUSIC_WEB_DEVELOPER_TOKEN='<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>' --env ICLOUD_APP_PASSWORD='<ICLOUD_APP_PASSWORD>' --env MCP_CONFIRM_SECRET='<MCP_CONFIRM_SECRET>' -- npx -y apple-icloud-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "apple-icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "apple-icloud-mcp"
      ],
      "env": {
        "APPLE_PRIVATE_KEY": "<APPLE_PRIVATE_KEY>",
        "APPLE_MUSIC_PRIVATE_KEY": "<APPLE_MUSIC_PRIVATE_KEY>",
        "APPLE_MAPS_PRIVATE_KEY": "<APPLE_MAPS_PRIVATE_KEY>",
        "APPLE_WEATHERKIT_PRIVATE_KEY": "<APPLE_WEATHERKIT_PRIVATE_KEY>",
        "APPLE_MUSIC_DEVELOPER_TOKEN": "<APPLE_MUSIC_DEVELOPER_TOKEN>",
        "APPLE_MUSIC_USER_TOKEN": "<APPLE_MUSIC_USER_TOKEN>",
        "APPLE_MUSIC_WEB_USER_TOKEN": "<APPLE_MUSIC_WEB_USER_TOKEN>",
        "APPLE_MUSIC_WEB_DEVELOPER_TOKEN": "<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>",
        "ICLOUD_APP_PASSWORD": "<ICLOUD_APP_PASSWORD>",
        "MCP_CONFIRM_SECRET": "<MCP_CONFIRM_SECRET>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "apple-icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "apple-icloud-mcp"
      ],
      "env": {
        "APPLE_PRIVATE_KEY": "<APPLE_PRIVATE_KEY>",
        "APPLE_MUSIC_PRIVATE_KEY": "<APPLE_MUSIC_PRIVATE_KEY>",
        "APPLE_MAPS_PRIVATE_KEY": "<APPLE_MAPS_PRIVATE_KEY>",
        "APPLE_WEATHERKIT_PRIVATE_KEY": "<APPLE_WEATHERKIT_PRIVATE_KEY>",
        "APPLE_MUSIC_DEVELOPER_TOKEN": "<APPLE_MUSIC_DEVELOPER_TOKEN>",
        "APPLE_MUSIC_USER_TOKEN": "<APPLE_MUSIC_USER_TOKEN>",
        "APPLE_MUSIC_WEB_USER_TOKEN": "<APPLE_MUSIC_WEB_USER_TOKEN>",
        "APPLE_MUSIC_WEB_DEVELOPER_TOKEN": "<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>",
        "ICLOUD_APP_PASSWORD": "<ICLOUD_APP_PASSWORD>",
        "MCP_CONFIRM_SECRET": "<MCP_CONFIRM_SECRET>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "apple-icloud-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "apple-icloud-mcp"
      ],
      "env": {
        "APPLE_PRIVATE_KEY": "<APPLE_PRIVATE_KEY>",
        "APPLE_MUSIC_PRIVATE_KEY": "<APPLE_MUSIC_PRIVATE_KEY>",
        "APPLE_MAPS_PRIVATE_KEY": "<APPLE_MAPS_PRIVATE_KEY>",
        "APPLE_WEATHERKIT_PRIVATE_KEY": "<APPLE_WEATHERKIT_PRIVATE_KEY>",
        "APPLE_MUSIC_DEVELOPER_TOKEN": "<APPLE_MUSIC_DEVELOPER_TOKEN>",
        "APPLE_MUSIC_USER_TOKEN": "<APPLE_MUSIC_USER_TOKEN>",
        "APPLE_MUSIC_WEB_USER_TOKEN": "<APPLE_MUSIC_WEB_USER_TOKEN>",
        "APPLE_MUSIC_WEB_DEVELOPER_TOKEN": "<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>",
        "ICLOUD_APP_PASSWORD": "<ICLOUD_APP_PASSWORD>",
        "MCP_CONFIRM_SECRET": "<MCP_CONFIRM_SECRET>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "apple-icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "apple-icloud-mcp"
      ],
      "env": {
        "APPLE_PRIVATE_KEY": "<APPLE_PRIVATE_KEY>",
        "APPLE_MUSIC_PRIVATE_KEY": "<APPLE_MUSIC_PRIVATE_KEY>",
        "APPLE_MAPS_PRIVATE_KEY": "<APPLE_MAPS_PRIVATE_KEY>",
        "APPLE_WEATHERKIT_PRIVATE_KEY": "<APPLE_WEATHERKIT_PRIVATE_KEY>",
        "APPLE_MUSIC_DEVELOPER_TOKEN": "<APPLE_MUSIC_DEVELOPER_TOKEN>",
        "APPLE_MUSIC_USER_TOKEN": "<APPLE_MUSIC_USER_TOKEN>",
        "APPLE_MUSIC_WEB_USER_TOKEN": "<APPLE_MUSIC_WEB_USER_TOKEN>",
        "APPLE_MUSIC_WEB_DEVELOPER_TOKEN": "<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>",
        "ICLOUD_APP_PASSWORD": "<ICLOUD_APP_PASSWORD>",
        "MCP_CONFIRM_SECRET": "<MCP_CONFIRM_SECRET>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "apple-icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "apple-icloud-mcp"
      ],
      "env": {
        "APPLE_PRIVATE_KEY": "<APPLE_PRIVATE_KEY>",
        "APPLE_MUSIC_PRIVATE_KEY": "<APPLE_MUSIC_PRIVATE_KEY>",
        "APPLE_MAPS_PRIVATE_KEY": "<APPLE_MAPS_PRIVATE_KEY>",
        "APPLE_WEATHERKIT_PRIVATE_KEY": "<APPLE_WEATHERKIT_PRIVATE_KEY>",
        "APPLE_MUSIC_DEVELOPER_TOKEN": "<APPLE_MUSIC_DEVELOPER_TOKEN>",
        "APPLE_MUSIC_USER_TOKEN": "<APPLE_MUSIC_USER_TOKEN>",
        "APPLE_MUSIC_WEB_USER_TOKEN": "<APPLE_MUSIC_WEB_USER_TOKEN>",
        "APPLE_MUSIC_WEB_DEVELOPER_TOKEN": "<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>",
        "ICLOUD_APP_PASSWORD": "<ICLOUD_APP_PASSWORD>",
        "MCP_CONFIRM_SECRET": "<MCP_CONFIRM_SECRET>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • APPLE_TEAM_IDYour Apple Developer Team ID (10 characters). Needed for Apple Music (official API), Apple Maps and WeatherKit.
  • APPLE_KEY_IDKey ID of a private key created in Certificates, Identifiers & Profiles → Keys with Media Services (MusicKit), MapKit JS and/or WeatherKit enabled.
  • APPLE_PRIVATE_KEYContents of that key's .p8 file (PEM; one-line values with \n escapes and base64 are accepted).
  • APPLE_PRIVATE_KEY_PATHLocal installs only: a path to the .p8 file instead of APPLE_PRIVATE_KEY.
  • APPLE_MUSIC_KEY_IDOptional per-service override of APPLE_KEY_ID for Apple Music (pair with APPLE_MUSIC_PRIVATE_KEY).
  • APPLE_MUSIC_PRIVATE_KEYOptional per-service override of APPLE_PRIVATE_KEY for Apple Music.
  • APPLE_MAPS_KEY_IDOptional per-service override of APPLE_KEY_ID for Apple Maps.
  • APPLE_MAPS_PRIVATE_KEYOptional per-service override of APPLE_PRIVATE_KEY for Apple Maps.
  • APPLE_WEATHERKIT_KEY_IDOptional per-service override of APPLE_KEY_ID for WeatherKit.
  • APPLE_WEATHERKIT_PRIVATE_KEYOptional per-service override of APPLE_PRIVATE_KEY for WeatherKit.
  • APPLE_WEATHERKIT_SERVICE_IDWeatherKit only: the Services ID registered for WeatherKit (e.g. com.example.weather).
  • APPLE_MUSIC_DEVELOPER_TOKENOptional: a pre-minted Apple Music developer token (JWT) instead of signing one from the key above.
  • APPLE_MUSIC_USER_TOKENMusic User Token for your library (official API), from a one-time MusicKit sign-in: `npx apple-icloud-mcp music-auth`. Without the Apple Developer key, ask the owner for a developer token (music-auth --print-developer-token) and run it with APPLE_MUSIC_DEVELOPER_TOKEN set. Lasts ~6 months.
  • APPLE_MUSIC_WEB_USER_TOKENOpt-in web-player mode (no developer account needed; unlocks rename/delete/remove/reorder): the media-user-token cookie from a signed-in music.apple.com tab.
  • APPLE_MUSIC_WEB_DEVELOPER_TOKENOptional override for the web-player developer token (normally read automatically from music.apple.com).
  • APPLE_MUSIC_STOREFRONTTwo-letter Apple Music storefront (e.g. us, gb). Default: your account's storefront, else us.
  • ICLOUD_USERNAMEYour Apple ID email, for iCloud Calendar, Contacts and Mail.
  • ICLOUD_APP_PASSWORDAn app-specific password from appleid.apple.com → Sign-In and Security → App-Specific Passwords (NOT your Apple ID password).
  • ICLOUD_MAIL_ADDRESSYour @icloud.com address, only if your Apple ID email is not an iCloud address (needed for Mail).
  • ICLOUD_DEFAULT_CALENDARCalendar new events go to when none is named (default: the first writable event calendar).
  • APPLE_WRITE_MODE"none" = read-only tools; "additive" = also create/append, never modify, delete or send; "all" = everything (default). Unrecognized values fail closed to "none".
  • APPLE_SERVICESComma-separated services to enable (music, calendar, contacts, mail, maps, weather, itunes). Default: all.
  • DISPLAY_TZIANA time zone (e.g. America/New_York) for displayed times and for dates you give without an offset. Set this on a hosted server, which runs in UTC.
  • APPLE_UNITS"metric" (default) or "imperial" units for weather (Maps distances always show both).
  • APPLE_STATE_CACHESet to false to write nothing under $MCP_DATA_DIR/.apple-icloud-mcp: no web-player token or iCloud discovery cache, and the rejected-password latch and spent confirmation tokens then last only as long as the process.
  • APPLE_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds (default 30000).
  • APPLE_DEBUG_LOGSet to 1 to log every upstream request line to stderr (credentials redacted).
  • MCP_CONFIRM_MODEHow confirm-gated writes (send mail, deletes, removing tracks, invitations) behave on a client with no prompt, like claude.ai: "ask-user" (default: preview + confirmToken, the model must get your OK), "auto", or "refuse". Unknown values mean refuse.
  • MCP_CONFIRM_ELICITATION"off" never shows a confirmation prompt, so every client gets the MCP_CONFIRM_MODE flow. Set it for a client that says it can prompt but never does (the gated call hangs, e.g. opencode 2.0.x). Any other value stays "on" (with a stderr warning).
  • MCP_CONFIRM_TTL_SECONDSLifetime of a confirmToken in seconds (default 600).
  • MCP_CONFIRM_SECRETSigning key for confirmTokens. Random per process by default; set it so a token issued just before a restart or redeploy still works (spent tokens are recorded on disk, so none can be replayed).

Tools this server provides (1)

Taken from the project documentation; the running server may differ.

apple_healthcheck
Reports which Apple services are configured and working.

What it does

Apple Music
Catalog search, library, playlists, history, recommendations and Replay.
iCloud Calendar
List, search, create, update and delete events and find free time.
iCloud Contacts and Mail
Search and edit contacts; read, send and reply to mail.
Apple Maps
Geocoding, place search, directions and ETAs.
WeatherKit
Current, hourly and daily forecasts and severe-weather alerts.
iTunes Search
Songs, albums, podcasts, apps, books and charts without credentials.
Write protection
Confirmation prompts and APPLE_WRITE_MODE limit what changes.

Good for

  • Build a playlist from a prompt
  • Find a free hour next week on your calendar
  • Check unread mail from one sender and draft a reply
  • Get drive time to the airport at a given hour
  • Look up a podcast's latest episodes

Pricing

Open source

Server is free; some Apple services need paid Apple accounts

Apple Icloud MCP FAQ

Does it need a Mac?

No, it runs on Linux, Windows or in a container.

What does it cost?

The server is free; Apple Music official access needs an Apple Developer Program membership ($99/yr) and an Apple Music subscription. Maps is free up to 25,000 calls a day and WeatherKit up to 500,000 a month.

Is it affiliated with Apple?

No. The README states it is unofficial.

How do I check it works?

Run apple_healthcheck first.

Which Node version?

Node.js 22 or later.

Is Apple Icloud MCP free?

Yes. Apple Icloud MCP is open source, so you can use and self-host it for free.

How do I add Apple Icloud MCP to Claude Code?

Run this command in your terminal: claude mcp add apple-icloud-mcp --env APPLE_PRIVATE_KEY='<APPLE_PRIVATE_KEY>' --env APPLE_MUSIC_PRIVATE_KEY='<APPLE_MUSIC_PRIVATE_KEY>' --env APPLE_MAPS_PRIVATE_KEY='<APPLE_MAPS_PRIVATE_KEY>' --env APPLE_WEATHERKIT_PRIVATE_KEY='<APPLE_WEATHERKIT_PRIVATE_KEY>' --env APPLE_MUSIC_DEVELOPER_TOKEN='<APPLE_MUSIC_DEVELOPER_TOKEN>' --env APPLE_MUSIC_USER_TOKEN='<APPLE_MUSIC_USER_TOKEN>' --env APPLE_MUSIC_WEB_USER_TOKEN='<APPLE_MUSIC_WEB_USER_TOKEN>' --env APPLE_MUSIC_WEB_DEVELOPER_TOKEN='<APPLE_MUSIC_WEB_DEVELOPER_TOKEN>' --env ICLOUD_APP_PASSWORD='<ICLOUD_APP_PASSWORD>' --env MCP_CONFIRM_SECRET='<MCP_CONFIRM_SECRET>' -- npx -y apple-icloud-mcp

What are the best alternatives to Apple Icloud MCP?

The closest alternatives to Apple Icloud MCP are TrendRadar, Ha MCP, Concord MCP, Getmitra and note1.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers