apple-icloud-mcp

apple-icloud-mcp

一个 Model Context Protocol 服务，可将 Claude 连接到Apple 的网络服务：Apple Music（你的播放列表、资料库和目录）、iCloud Calendar、Contacts 和 Mail、Apple Maps、WeatherKit，以及 iTunes Search API。

它通过 Apple 自有的 Web API 和标准协议（CalDAV、CardDAV、IMAP/SMTP）在网络上与 Apple 通信。因此，与仅适用于 Mac 的 Apple 集成（例如 apple-swift-mcp）不同，它可以在任何地方运行：Linux、Windows、容器，或托管在 mcp-host 上，作为 claude.ai 连接器。这两个项目互为补充：apple-swift-mcp 操控 Mac 自带的应用（Calendar、Reminders、Contacts、Mail、Messages、Notes、Photos、Maps 和 Music.app 播放列表），而 apple-icloud-mcp 可从任何地方访问 Apple 的网络服务，并提供 Apple Music 目录、WeatherKit 和 iTunes。

说明

非官方项目。 本项目与 Apple Inc. 无关联，也未获其认可或赞助。Apple、iCloud、Apple Music、Apple Maps 和 WeatherKit 均为 Apple Inc. 的商标，此处仅用于指称本项目连接的服务。

警告

由 AI 开发的项目。 本代码库完全由 Claude Code 构建并积极维护。没有任何人工审核过实现。使用前请检查所有代码和工具权限。

重要

尚未通过真实 Apple 账户验证。 所有请求格式均依据 Apple 文档或 Apple 自有的 Web 客户端，并通过针对高保真模拟对象的测试覆盖，但构建环境中没有 Apple 凭据。首次真实运行才是真正的验证——请先运行 apple_healthcheck，并参阅 docs/APPLE-API.md，了解每个调用所依赖的内容。

你可以做什么

• “创建一个名为 Road Trip 2026 的播放列表，加入 20 首欢快的 80 年代歌曲”
• “将 Taylor Swift 最新专辑中的前 5 首歌曲添加到我的 Workout 播放列表”
• “从我的 Chill 播放列表中删除重复歌曲，并按艺人排序”（Web 播放器模式）
• “我最近经常循环收听哪些歌曲？” / “显示我今年的 Apple Music Replay”
• “我下周的日历上有什么安排？” / “帮我找周四下午一个空闲小时”
• “把我的牙医预约改到周五下午 3 点”
• “Jane 的电话号码是多少？” / “将来自 Acme 的 Bob Lee（[email protected]）添加到我的联系人”
• “房东有没有发来未读邮件？” / “回复 Sam 的上一条消息，说我会到”
• “下午 5 点开车去机场要多久？” / “Union Square 附近的咖啡店”
• “芝加哥明天会下雨吗？”
• “查找播客 Hard Fork，并列出最新几期” / “英国目前最热门的专辑有哪些？”

服务及各自所需条件

所有服务均为可选项：仅当存在相应凭据时才会启用，apple_healthcheck 会告知你哪些服务正常运行。

服务	功能	凭据	费用
Apple Music（官方 API）	目录搜索、排行榜、你的资料库、播放列表（创建、添加曲目、文件夹）、历史记录、推荐、Replay、评分、收藏	Apple Developer 密钥 + Music User Token	Apple Developer Program（$99/年）+ Apple Music 订阅
Apple Music（网页播放器模式，自选，非官方）	包含以上所有功能，另加重命名/删除播放列表、移除/重新排序/排序/去重曲目、移至文件夹、从资料库移除	来自 music.apple.com 的 media-user-token Cookie	仅需 Apple Music 订阅
iCloud Calendar（CalDAV）	列出/搜索事件（展开重复事件）、创建/更新/删除（正确处理时区和重复规则）、空闲时间查找器	Apple ID + App 专用密码	免费
iCloud Contacts（CardDAV）	搜索、读取、创建、更新（按电子邮件/电话分别编辑）、删除、群组	Apple ID + App 专用密码	免费
iCloud Mail（IMAP/SMTP）	列出邮箱、搜索、读取（不标记为已读）、发送和回复、标记、移动	Apple ID + App 专用密码	免费
Apple Maps（Maps Server API）	地理编码、反向地理编码、地点搜索、路线、预计到达时间、已签名的地图图片 URL	Apple Developer 密钥	每天 25,000 次调用以内免费
WeatherKit	当前天气状况、逐小时/逐日预报、未来一小时降水、恶劣天气警报	Apple Developer 密钥 + Services ID	每月 500,000 次调用以内免费
iTunes Search + charts	搜索/查询歌曲、专辑、播客（含单集）、应用、图书、有声书；热门排行榜	无	免费

要求

• Node.js 22 或更高版本（托管运行器使用 Node 26）。
• 你想使用的服务所需的条件（见上表）。

条款确认

使用此 MCP 服务，即表示你知悉并同意以下内容：

1. 它只访问你自己的 Apple 账户，并使用你提供的凭据。它无法访问其他人的数据；在共享部署中，每个人的 Apple ID 都保留在各自的进程中。

2. 你的使用受 Apple 条款约束，就像你直接使用 Apple 服务一样——尤其是 Apple 媒体服务条款、iCloud 条款与条件，以及适用于开发者密钥服务的 Apple Developer Program 许可协议。iCloud 条款规定，你不得 “干扰或扰乱服务（包括通过脚本或网络爬虫等任何自动化方式访问服务）”。这里的 iCloud 功能使用 Apple 为第三方应用提供的机制——通过 CalDAV、CardDAV 和 IMAP/SMTP 使用专用密码——其使用速度相当于有人通过助手操作。Apple Music 网页播放器模式则有所不同：它使用 Apple 的私有网页播放器 API 和你的浏览器会话，Apple 表示可能随时封锁该模式。除非你主动启用，否则该模式处于关闭状态。维护者查阅的条款日期为 2026-09-26。

**3. 仅供个人使用。**本项目与 Apple Inc. 无关，也未获其认可或赞助。“Apple”、“Apple Music”、“iCloud”及相关标志均属于 Apple。请勿分享你的凭据，也不要使用本项目批量提取数据。

**4. 写入操作会产生实际影响。**创建包含参与者的日历事件会让 iCloud 向他们发送邀请；发送邮件会实际发出邮件；删除播放列表或联系人会将其删除。这些操作会先要求确认（参见确认），而 APPLE_WRITE_MODE 则可以彻底移除写入工具。

5. 你须对后果承担全部责任，无论是技术方面的后果（速率限制、反复登录失败后账户被锁定）还是其他后果。

这是维护者本着诚信所作的摘要，并非法律建议，也不会修改或取代 Apple 的实际条款。

安装

Claude Code

claude mcp add apple -- npx -y apple-icloud-mcp

然后为所需服务设置变量（参见设置凭据），并填入服务的 env，例如 .mcp.json：

{
  "mcpServers": {
    "apple": {
      "command": "npx",
      "args": ["-y", "apple-icloud-mcp"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_APP_PASSWORD": "abcd-efgh-ijkl-mnop",
        "DISPLAY_TZ": "America/New_York"
      }
    }
  }
}

Claude Desktop

从最新版本安装 .mcpb 程序包并填写其要求的设置，或者将相同的 npx 配置项添加到 claude_desktop_config.json。

从源代码安装

git clone https://github.com/chrischall/apple-icloud-mcp.git && cd apple-icloud-mcp
npm install && npm run build
cp .env.example .env   # fill in what you need
npm run dev

设置凭据

iCloud 日历、通讯录和邮件——应用专用密码

1. 登录 appleid.apple.com → 登录与安全 → 应用专用密码 → 生成一个密码（必须启用双重认证）。
2. 设置 ICLOUD_USERNAME（你的 Apple ID 邮箱）和 ICLOUD_APP_PASSWORD（xxxx-xxxx-xxxx-xxxx 格式的密码）。此处无法使用你的常规 Apple ID 密码。
3. 如果你的 Apple ID 不是 @icloud.com / @me.com 地址，还需设置 ICLOUD_MAIL_ADDRESS，填写你的 iCloud 邮件地址（仅限邮件服务）。

更改 Apple ID 密码会撤销所有应用专用密码——这是原本正常的配置突然返回“凭据被拒绝”的常见原因。若密码被明确拒绝，服务将停止发送该密码——持续 24 小时或直到你更改密码，即使重启也会如此（服务会记录被拒绝凭据对的摘要，而不会记录密码）——因为反复登录失败可能会锁定 Apple ID。

不支持提醒事项：从 iOS 13 开始，iCloud 提醒事项不再通过 CalDAV 同步（参见不支持的功能及原因）。

Apple Developer 密钥 — Apple Music（官方）、Apple Maps、WeatherKit

这三项服务都需要付费加入 Apple Developer Program。

1. 在 Certificates, Identifiers & Profiles 中， 为所需服务创建标识符：Media ID（Apple Music）、Maps ID（Apple Maps） 和 Services ID（WeatherKit）。
2. 在 Keys 下创建密钥，并勾选 Media Services (MusicKit)、MapKit JS 和／或 WeatherKit。 一个密钥可以同时用于这三项服务。下载 .p8 文件（只有一次机会）。
3. 设置 APPLE_TEAM_ID、APPLE_KEY_ID 和 APPLE_PRIVATE_KEY（.p8 文件内容——多行 PEM、包含 \n 转义符的 单行值或 base64 均可）。对于 WeatherKit，还要设置 APPLE_WEATHERKIT_SERVICE_ID。也支持为各项服务分别设置密钥，使用 APPLE_MUSIC_KEY_ID / APPLE_MUSIC_PRIVATE_KEY、APPLE_MAPS_… 和 APPLE_WEATHERKIT_…。

服务会自行签发短期令牌（Apple Music 的有效期为 12 小时，Maps 和 WeatherKit 为 1 小时）。

Apple Music — 你的资料库（官方 API）：Music User Token

仅凭开发者密钥即可搜索目录。使用你的资料库和播放列表还需要 Music User Token，Apple 只会通过浏览器中交互式的 MusicKit 登录流程签发此令牌。设置好开发者密钥后，运行：

npx apple-icloud-mcp music-auth

这会打开一个位于 127.0.0.1 的页面，点击 Sign in with Apple Music 后，页面会显示 APPLE_MUSIC_USER_TOKEN=…。将此值设置为 APPLE_MUSIC_USER_TOKEN。其有效期约为六个月，并与签发该令牌的开发者密钥绑定；更改 Apple ID 密码会撤销此令牌。

没有开发者密钥的人（例如共享部署中的其他人）完全不需要 .p8 文件。密钥所有者运行 npx apple-icloud-mcp music-auth --print-developer-token --days 7，并将输出的短期令牌发送给他们；他们在自己的 设备上运行 APPLE_MUSIC_DEVELOPER_TOKEN=<that token> npx apple-icloud-mcp music-auth，登录后保存输出的用户令牌。开发者令牌会自行过期；用户令牌仍可与服务端的密钥配合使用。

Apple Music — 网页播放器模式（可选，非官方）

Apple 官方 API 无法重命名或删除播放列表、移除或重新排序曲目，也无法从资料库中移除内容。Apple 自家的网页播放器可以做到。网页播放器模式会通过你的浏览器会话使用同一私有 API：

1. 在桌面浏览器中登录 music.apple.com。
2. 打开开发者工具 → Application/Storage → Cookies → https://music.apple.com，复制 media-user-token Cookie 的值。
3. 将其设置为 APPLE_MUSIC_WEB_USER_TOKEN。

网页播放器自己的开发者令牌会从 music.apple.com 自动读取（并缓存）。此模式也不需要 Apple Developer 账户。Apple 不支持此模式，且可能在不另行通知的情况下停止工作；需要此模式的工具会在说明中注明，其响应也会报告使用了哪个后端（official 或 web）。

提示

在 Mac 上，你或许根本不需要网页播放器模式。 apple-swift-mcp 可通过 Music 自带的脚本功能，在本地 Music.app 资料库中进行相同的播放列表编辑操作——重命名、删除、移除、重新排序、排序、去重以及移入文件夹，无需令牌或开发者账户。此方式适用于已在资料库中的歌曲，因此仍需先将目录中的歌曲添加到资料库（此处使用 apple_music_add_to_library）。

在 mcp-host 上运行

注册 apple-icloud-mcp 时，mcp-host 会读取软件包附带的 mint.yaml：

• 所有者设置（开发者密钥、APPLE_WRITE_MODE、APPLE_SERVICES、MCP_CONFIRM_SECRET 等）放在注册的环境中——将私钥和确认密钥保存为机密。
• 所有个人信息（Apple ID、应用专用密码、Music 令牌、iCloud Mail 地址、时区、默认日历、Apple Music 店面）都声明为 auth.fields，这样 mcp-host 会在每个人连接时询问，并按人记住答案；每位调用者都有自己的进程和数据目录。
• 状态：dataDir 存放少量小文件（参见安全性），让缩容至零后的冷启动开销保持低，同时防止已撤销的密码或已用过的确认令牌在重启后被重复使用。
• 出站连接：仅允许此服务调用的 Apple 主机（api.music.apple.com、amp-api.music.apple.com、music.apple.com、caldav.icloud.com、contacts.icloud.com、*.icloud.com、imap.mail.me.com、smtp.mail.me.com、maps-api.apple.com、weatherkit.apple.com、itunes.apple.com、rss.marketingtools.apple.com）。HTTPS 通过 Node 内置的 fetch 经由运行器的代理连接；IMAP 和 SMTP 则通过 HTTP CONNECT 经由同一代理建立隧道。

请提供你的时区（DISPLAY_TZ）：运行器使用 UTC，而不带时区偏移的时间（“3pm”）会按 DISPLAY_TZ 解读——没有自身时区的日历事件（“floating”）也一样，无论调用传入什么 timeZone。确认令牌会自动在重启后保留：mcp-host 会为带有 dataDir 的子进程提供稳定的专属密钥（MCP_HOST_CONFIRM_SECRET），因此子进程空闲退出（或重新部署）后，先前批准的预览仍然有效。已用令牌会记录在磁盘上，因此无法重放。所有者设置的 MCP_CONFIRM_SECRET 优先于主机密钥。

工具

共 59 个工具。模式是注册该工具所需的最低 APPLE_WRITE_MODE；确认标记需要先确认的工具（详情）；🌐 标记需要网页播放器模式的 Apple Music 工具。

健康检查

工具	功能	模式	确认
apple_healthcheck	检查 Apple 服务（Apple Music、iCloud Calendar、Contacts、Mail、Apple Maps、WeatherKit、iTunes）的配置和可访问性。	read

Apple Music

工具	功能	模式	确认
apple_music_search_catalog	按文本搜索 Apple Music 曲库中的歌曲、专辑、艺人、播放列表、音乐视频或电台。	read
apple_music_get_catalog_items	按 ID 查找 Apple Music 曲库中的歌曲、专辑、艺人、播放列表、音乐视频或电台；也可按 ISRC 查找歌曲或音乐视频，按 UPC 查找专辑。	read
apple_music_get_charts	获取 Apple Music 某个店面最热门的歌曲、专辑、播放列表和音乐视频；还可指定单个音乐流派。	read
apple_music_list_playlists	列出 Apple Music 资料库中的播放列表（按字母顺序排列），或列出某个播放列表文件夹的内容（文件夹和播放列表）。	read
apple_music_get_playlist	查看一个播放列表及其曲目顺序：资料库播放列表（p.…）或曲库播放列表（pl.…）。	read
apple_music_list_folders	列出 Apple Music 资料库中的播放列表文件夹：顶层文件夹，或某个文件夹的子文件夹。	read
apple_music_search_library	按文本搜索你自己的 Apple Music 资料库（而非整个曲库）中的歌曲、专辑、艺人、播放列表或音乐视频。	read
apple_music_list_library	列出 Apple Music 资料库中的内容：所有歌曲、专辑、艺人或音乐视频（按字母顺序分页），或最近添加的项目。	read
apple_music_get_history	查看你最近在 Apple Music 上收听的内容：最近播放的专辑、播放列表和电台、最近播放的歌曲、最近收听的电台或高频播放内容。	read
apple_music_get_recommendations	查看 Apple Music 为你提供的个性化推荐（“为你打造”“最近播放”等类似分组），每组包含其标题以及其中的专辑、播放列表或电台（曲库 ID）。	read
apple_music_get_replay	查看 Apple Music Replay：最新 Replay 年度的热门歌曲、专辑和艺人，或指定年度的内容（Apple 提供时包含播放次数）。	read
apple_music_get_ratings	查看你是否喜欢或不喜欢歌曲、专辑、播放列表、音乐视频或电台（曲库或资料库 ID），并返回每个 ID 对应的喜欢、不喜欢或无评价状态。	read
apple_music_create_playlist	在 Apple Music 资料库中创建播放列表，可选择添加曲目（最多 500 个曲库或资料库歌曲 ID，每次添加 100 个）、填写描述、指定文件夹并设置公开状态（APPLE_WRITE_MODE=additive 时不可用）。	additive
apple_music_add_playlist_tracks	将歌曲（最多 500 个曲库或资料库 ID）追加到资料库播放列表末尾。	additive
apple_music_create_folder	在 Apple Music 资料库的顶层或其他文件夹中创建播放列表文件夹。	all
apple_music_add_to_library	按曲库 ID 将歌曲、专辑、播放列表或音乐视频添加到 Apple Music 资料库（每种类型最多 100 个）。	additive
apple_music_add_favorites	按曲库 ID 将歌曲、专辑、播放列表、艺人或音乐视频标记为个人收藏（即 Apple Music 中的星标；收藏的歌曲会添加到“最爱歌曲”播放列表，每种类型最多 100 个）。	additive
apple_music_set_rating	为歌曲、专辑、播放列表、音乐视频或电台设置评价（曲库或资料库 ID）：喜欢、不喜欢，或清除评价。	all
apple_music_update_playlist 🌐	重命名 Apple Music 资料库中的播放列表、修改其描述，或将其设为公开或私密。	all
apple_music_remove_playlist_tracks 🌐	按资料库曲目 ID 和／或从 1 开始的位置（来自 apple_music_get_playlist）从资料库播放列表中移除曲目。	all	yes
apple_music_reorder_playlist 🌐	调整资料库播放列表的顺序：移动曲目、排序（按名称、艺人、专辑、发行日期、时长或添加日期）、反转顺序、去重（每首歌曲保留第一个副本），或用曲目 ID 的完整新顺序替换现有顺序（可能会移除曲目）。	all	yes
apple_music_move_playlist 🌐	将资料库播放列表移入播放列表文件夹，或移回顶层（“root”）。	all
apple_music_delete_playlist 🌐	删除资料库中的播放列表（歌曲仍保留在资料库中）。	all	yes
apple_music_remove_from_library 🌐	按资料库 ID 从 Apple Music 资料库中移除歌曲、专辑、音乐视频或播放列表（apple_music_list_library / apple_music_search_library 返回的 i.…、l.…、p.…，每次最多 50 个；预览会列出每项的名称）。	all	yes
apple_music_remove_favorites 🌐	按曲库 ID 取消歌曲、专辑、播放列表、艺人或音乐视频的个人收藏（星标），每种类型最多 100 个。	all

iCloud 日历

工具	功能	模式	确认
apple_calendar_list_calendars	列出你的 iCloud 日历（仅限事件日历）：ID、名称、颜色、你是否可以向其中添加事件、日历是否为共享日历（shared：他人与你共享；sharedByYou：你与他人共享），以及新事件默认添加到哪个日历。	读取
apple_calendar_list_events	列出指定日期范围内的 iCloud 日历事件（约会、会议），将重复事件展开为各次事件，并按开始时间排序。	读取
apple_calendar_search_events	在指定日期范围内按文本搜索 iCloud 日历事件（不区分大小写，匹配标题、位置或备注）：fromDate（默认为今天；可以是过去的日期）+ toDate 或 daysAhead（默认为 30），最多 366 天。	读取
apple_calendar_get_event	根据列表或搜索结果返回的 ID，获取一条完整的 iCloud 日历事件（备注不截断，包含参与者、提醒以及以通俗英语描述的重复规则）。	读取
apple_calendar_create_event	创建 iCloud 日历事件：标题、startDate/endDate（定时事件默认 1 小时；全天事件的 endDate 为最后一天）、位置、备注、url、提醒、重复规则、参与者。	添加	有参与者时
apple_calendar_update_event	更改 iCloud 日历事件：标题、startDate/endDate、isAllDay、位置、备注、url（"" 可清除）、提醒、参与者（完整的新列表）、日历（将事件移至其他日历）。	全部	有参与者时
apple_calendar_delete_event	删除 iCloud 日历事件。重复事件：范围可选 thisEvent（默认；由 "#occ=" ID 指定的单次事件）、futureEvents（此事件及所有后续事件）或 allEvents（整个系列）。	全部	是
apple_calendar_find_free_time	在你的 iCloud 日历中查找空闲时间：在工作时间内（workdayStart/workdayEnd，默认为 09:00–17:00，默认仅限工作日）查找每天至少持续 minDurationMinutes（默认为 30 分钟）的空闲时段。	读取

iCloud 联系人

工具	功能	模式	确认
apple_contacts_search	按姓名、昵称、公司、职位、电子邮件或电话号码数字搜索用户的 iCloud 联系人（通讯录），也可以仅在一个联系人群组内搜索。	读取
apple_contacts_get	根据 ID（来自 apple_contacts_search）获取一位联系人的完整信息：姓名、组织、职位、电子邮件、电话、邮寄地址和 URL（每项都包含标签和 apple_contacts_update 可指定的 entryId）、生日、备注、……	读取
apple_contacts_list_groups	列出 iCloud 联系人中的群组（如家庭、工作）：每个群组的 ID、名称和成员数量。	读取
apple_contacts_create	在 iCloud 联系人中创建新联系人。必须提供 givenName、familyName 或 organization；可选提供 middleName、nickname、department、jobTitle、note、birthday（YYYY-MM-DD，或不含年份的 --MM-DD），以及电子邮件、电话、URL 和邮政地址列表……	添加
apple_contacts_update	就地编辑现有 iCloud 联系人。标量字段（givenName、familyName、middleName、nickname、organization、department、jobTitle、note、birthday）会替换当前值；"" 可清除字段。	全部
apple_contacts_delete	根据 ID 永久删除 iCloud 联系人中的一位联系人（在所有设备上删除）。	全部	是

iCloud Mail

工具	功能说明	模式	确认
apple_mail_list_mailboxes	列出 iCloud Mail 邮箱（文件夹）：路径、名称、特殊用途（收件箱、已发送、草稿、废纸篓、垃圾邮件、归档），默认还包括邮件数和未读邮件数。	read
apple_mail_search	在一个 iCloud Mail 邮箱（默认为 INBOX）中按发件人、收件人、主题、全文、收件日期范围、未读状态和标记状态搜索邮件。	read
apple_mail_get_message	根据 uid 读取一封 iCloud Mail 邮件（来自 apple_mail_search）：邮件头（发件人、收件人、抄送、回复地址、日期、主题、message-id）、纯文本正文（没有文本部分时会将 HTML 转换为易读文本）、截断标记和附件…	read
apple_mail_download_attachment	使用 apple_mail_get_message 返回的 1 起始索引，将一个附件下载为嵌入式二进制资源；默认上限为 10 MiB，最大为 20 MiB，且不会将邮件标记为已读。	read
apple_mail_send	从你的 iCloud Mail 地址发送纯文本邮件（收件人/抄送/密送、主题、正文；不支持附件）。	all	是
apple_mail_update_flags	根据 uid 将 iCloud Mail 邮件标记为已读或未读，以及加标记或取消标记（uid 来自 apple_mail_search，单个邮箱中为 1–100 个）。	all
apple_mail_move	将 iCloud Mail 邮件（uid 来自 apple_mail_search，单个邮箱中为 1–100 个）移至其他邮箱：使用 apple_mail_list_mailboxes 返回的路径或别名（inbox、archive、trash、junk、sent、drafts）。	all

Apple Maps

工具	功能说明	模式	确认
apple_maps_geocode	使用 Apple Maps 将地址或地点名称转换为坐标（地理编码）。	read
apple_maps_reverse_geocode	使用 Apple Maps 查找纬度/经度对应的街道地址（反向地理编码），例如“37.33,-122.01 在哪里？”。	read
apple_maps_search	在 Apple Maps 中搜索地点：商家、兴趣点、地址、地标（例如“咖啡”“电动汽车充电桩”“金门大桥”）。	read
apple_maps_directions	使用 Apple Maps 查询两个地点之间的驾车、步行或骑行路线（地址或“lat,lng”）。	read
apple_maps_etas	使用 Apple Maps 查询从一个地点到最多 10 个目的地的行程时间和距离，支持驾车（实时路况）、公共交通、步行或骑行（例如“开车去这些商店，哪家最近？”）。	read
apple_maps_lookup_place	根据地点 ID 查询 Apple Maps 地点：ID 是 apple_maps_search、apple_maps_geocode 或 apple_maps_reverse_geocode 结果中的 id 字段；一次查询 1 至 50 个。	read
apple_maps_snapshot_url	创建静态 Apple Maps 图像（PNG）的签名链接：以地址或“lat,lng”为中心，和/或添加图钉（每个图钉可选标签、颜色和单字符字形；未指定中心时，地图会自动适配图钉范围）。	read

WeatherKit

工具	功能说明	模式	确认
apple_weather_get	获取 Apple Weather（WeatherKit）提供的地点天气预报：当前天气状况、逐小时预报（最多 240 h）、逐日预报（最多 10 天）、未来一小时降雨、恶劣天气警报（需要 countryCode）。	read
apple_weather_get_alert	根据 ID 获取 Apple Weather（WeatherKit）一条恶劣天气警报的完整官方原文，不作修改（ID 为调用 apple_weather_get 并提供 countryCode 后返回的 alerts[].id）。	read

iTunes 搜索和排行榜

工具	功能	模式	确认
apple_itunes_search	搜索 Apple 的 iTunes Store 目录，包括歌曲、专辑、艺人、播客和播客单集、有声书、应用和电子书；无需 Apple 账户或密钥。	读取
apple_itunes_lookup	查询 iTunes Store 项目（无需 Apple 账户或密钥）：可按 ID 查询 1–200 个 trackId/collectionId/artistId 值，例如来自 apple_itunes_search 或 Apple Music 链接的值；也可按一个 UPC/EAN（专辑）、ISBN（图书）或 bundleId（应用）查询。	读取
apple_charts_get	Apple 当前排行榜（无需 Apple 账户或密钥）：Apple Music 播放次数最多的歌曲、专辑、音乐视频和播放列表；热门播客、趋势播客单集和热门订阅频道；热门免费/付费应用和图书；热门有声书。	读取

写入保护（APPLE_WRITE_MODE）

值	已注册的内容
none	仅限读取工具。
additive	读取工具，以及只会向你自己的账户添加内容的写入操作：创建（私人）播放列表、追加曲目、添加到资料库/收藏夹、创建活动（不含参与者，且不在与他人共享的日历中）或联系人。不会修改或删除任何现有内容，也不会向任何人发送内容。
all（默认）	所有操作。

低于其模式门槛的工具根本不会注册，因此任何提示词或注入指令都无法调用它们。 无法识别的值将安全地默认为 none。APPLE_SERVICES（逗号分隔：music、calendar、 contacts、mail、maps、weather、itunes）会进一步限制实际注册工具的服务范围。

确认（MCP_CONFIRM_MODE）

不可逆操作以及任何会联系到他人的操作都必须先确认：发送邮件、 删除活动、联系人、播放列表或资料库项目、移除或重新排序播放列表曲目，以及 创建或修改包含参与者的活动（iCloud 会向他们发送邮件）。能够显示提示的客户端 （Claude Code）会直接询问你，除非 MCP_CONFIRM_ELICITATION=off。无法显示提示的客户端（claude.ai）会采用两步流程：首次调用不执行任何操作， 并返回预览和 confirmToken；只有使用该令牌再次调用才会执行操作，如果目标在此期间发生变化，则会拒绝执行。

变量	含义
MCP_CONFIRM_MODE	ask-user（默认——模型必须在重试调用前获得你的同意）、auto（模型查看预览后可自行确认）、refuse（始终拒绝）。未知值视为 refuse。
MCP_CONFIRM_ELICITATION	on（默认）或 off。off 时不会显示提示，因此在 MCP_CONFIRM_MODE 下所有客户端都会采用两步流程。对于声称能显示提示但实际不会显示的客户端（受限调用会挂起——opencode 2.0.x），请设置此项。其他任何值都会保持为 on（并输出 stderr 警告）。
MCP_CONFIRM_TTL_SECONDS	令牌有效时长（默认 600）。
MCP_CONFIRM_SECRET	令牌签名密钥；默认情况下每个进程随机生成（在 mcp-host 上，如果设置了绝对路径的 MCP_DATA_DIR，则改用主机为每个子进程设置的 MCP_HOST_CONFIRM_SECRET）。设置此项可使令牌在重启后继续有效；已使用的令牌会记录在磁盘上（mcp-utils 的共享存储、$MCP_DATA_DIR/.mcp-confirm/spent/，或者未设置绝对路径的 MCP_DATA_DIR 时使用 ~/.apple-icloud-mcp/confirm-spent/），因此无法重放。如果设置了 APPLE_STATE_CACHE=false，令牌只会由进程记住（并发出相应警告）；如果目录不可写，为避免重放风险，将拒绝已确认的写入操作。

环境变量

全部为可选项；每项服务在提供相应凭据后启用。空白值、undefined、null 或尚未展开的 ${VAR} 均视为未设置。

Apple Developer 密钥

变量	含义
APPLE_TEAM_ID	你的 Apple Developer Team ID（10 个字符）。Apple Music（官方 API）、Apple Maps 和 WeatherKit 所需。
APPLE_KEY_ID	在 Certificates, Identifiers & Profiles → Keys 中创建的私钥对应的 Key ID，创建时需启用 Media Services（MusicKit）、MapKit JS 和／或 WeatherKit。
APPLE_PRIVATE_KEY 🔒	该密钥的 .p8 文件内容（PEM 格式；接受带有 \n 转义符的单行值和 base64）。
APPLE_PRIVATE_KEY_PATH	仅限本地安装：.p8 文件的路径，用于替代 APPLE_PRIVATE_KEY。
APPLE_MUSIC_KEY_ID	可选的 Apple Music 专属覆盖值，用于替代 APPLE_KEY_ID（需与 APPLE_MUSIC_PRIVATE_KEY 配合使用）。
APPLE_MUSIC_PRIVATE_KEY 🔒	可选的 Apple Music 专属覆盖值，用于替代 APPLE_PRIVATE_KEY。
APPLE_MAPS_KEY_ID	可选的 Apple Maps 专属覆盖值，用于替代 APPLE_KEY_ID。
APPLE_MAPS_PRIVATE_KEY 🔒	可选的 Apple Maps 专属覆盖值，用于替代 APPLE_PRIVATE_KEY。
APPLE_WEATHERKIT_KEY_ID	可选的 WeatherKit 专属覆盖值，用于替代 APPLE_KEY_ID。
APPLE_WEATHERKIT_PRIVATE_KEY 🔒	可选的 WeatherKit 专属覆盖值，用于替代 APPLE_PRIVATE_KEY。
APPLE_WEATHERKIT_SERVICE_ID	仅限 WeatherKit：为 WeatherKit 注册的 Services ID（例如 com.example.weather）。

Apple Music

变量	含义
APPLE_MUSIC_DEVELOPER_TOKEN 🔒	可选：预先生成的 Apple Music 开发者令牌（JWT），用于替代使用上述密钥签名生成的令牌。
APPLE_MUSIC_USER_TOKEN 🔒	你的资料库对应的 Music User Token（官方 API），通过一次性 MusicKit 登录获取：npx apple-icloud-mcp music-auth。如果没有 Apple Developer 密钥，请向所有者索取开发者令牌（music-auth --print-developer-token），并在设置 APPLE_MUSIC_DEVELOPER_TOKEN 后运行。有效期约 6 个月。
APPLE_MUSIC_WEB_USER_TOKEN 🔒	自选的网页播放器模式（无需开发者帐户；解锁重命名／删除／移除／重新排序功能）：从已登录的 music.apple.com 标签页获取 media-user-token cookie。
APPLE_MUSIC_WEB_DEVELOPER_TOKEN 🔒	可选的网页播放器开发者令牌覆盖值（通常会从 music.apple.com 自动读取）。
APPLE_MUSIC_STOREFRONT	Apple Music 商店区域代码（两位字母，例如 us、gb）。默认值：你的帐户所属商店区域；若无法确定，则为 us。

iCloud

变量	含义
ICLOUD_USERNAME	你的 Apple ID 电子邮件地址，用于 iCloud Calendar、Contacts 和 Mail。
ICLOUD_APP_PASSWORD 🔒	在 appleid.apple.com → Sign-In and Security → App-Specific Passwords 中生成的 App 专用密码（不是你的 Apple ID 密码）。
ICLOUD_MAIL_ADDRESS	仅当你的 Apple ID 电子邮件地址不是 iCloud 地址时，填写你的 @icloud.com 地址（Mail 所需）。
ICLOUD_DEFAULT_CALENDAR	未指定日历时，新事件将添加到此日历（默认值：第一个可写入的事件日历）。

行为

变量	含义
APPLE_WRITE_MODE	"none" = 只读工具；"additive" = 还可创建/追加，但绝不修改、删除或发送；"all" = 全部（默认）。无法识别的值会安全回退为 "none"。
APPLE_SERVICES	要启用的服务，使用逗号分隔（music、calendar、contacts、mail、maps、weather、itunes）。默认：全部。
DISPLAY_TZ	用于显示时间以及未提供时区偏移的日期的 IANA 时区（例如 America/New_York）。没有自身时区的日历事件（浮动事件）始终按此时区读取：日历调用的 timeZone 会改变时间的读取和显示方式（以及创建/更新时事件的存储时区），但绝不会改变浮动事件的读取方式，因此 occurrence id 永远不取决于它。在托管服务上设置此项，该服务以 UTC 运行。
APPLE_UNITS	天气使用 "metric"（默认）或 "imperial" 单位（地图距离始终同时显示两种单位）。
APPLE_STATE_CACHE	设为 false 后，不会在 $MCP_DATA_DIR/.apple-icloud-mcp 下写入任何内容：没有网页播放器令牌或 iCloud 发现缓存，拒绝密码的锁定标记和已用确认令牌也只会在进程运行期间保留。
APPLE_REQUEST_TIMEOUT_MS	每个请求的超时时间，单位为毫秒（默认 30000）。
APPLE_DEBUG_LOG	设为 1 后，将每一行上游请求记录到 stderr（凭据会脱敏）。

确认

变量	含义
MCP_CONFIRM_MODE	对于没有提示词功能的客户端（如 claude.ai），确认门控写入（发送邮件、删除、移除曲目、邀请）的处理方式："ask-user"（默认：预览 + confirmToken，模型必须获得你的同意）、"auto" 或 "refuse"。未知值表示拒绝。
MCP_CONFIRM_ELICITATION	"off" 表示绝不显示确认提示，因此每个客户端都会使用 MCP_CONFIRM_MODE 流程。对于声称支持提示但实际上从不提示的客户端（门控调用会一直挂起，例如 opencode 2.0.x），请设置此项。任何其他值都会保持为 "on"（并显示 stderr 警告）。
MCP_CONFIRM_TTL_SECONDS	confirmToken 的有效期，单位为秒（默认 600）。
MCP_CONFIRM_SECRET 🔒	confirmTokens 的签名密钥。默认情况下每个进程随机生成；设置此项后，在重启或重新部署之前签发的令牌仍可使用（已用令牌会记录到磁盘，因此无法重放）。

🔒 = 秘密：请将其作为机密存储。

不支持的功能（及原因）

• 提醒事项、备忘录、查找、iCloud 云盘、照片、隐藏邮件地址。 这些功能都没有可用的公共 API 或仍能正常工作的标准协议：iCloud 提醒事项在 iOS 13 中退出了 CalDAV。唯一途径是使用 iCloud.com 的私有 API，它需要你的完整 Apple ID 密码、SRP 登录和双重认证验证码，在大约两年内已失效四次，会被高级数据保护功能拦截，而且正是 iCloud 条款所禁止的“自动化手段”。在 Mac 上，apple-swift-mcp 可原生支持提醒事项、备忘录和照片。
• 播放音乐。 Apple 的 Web API 用于管理你的资料库；播放则在 Apple Music 应用中进行。
• 创建或删除日历——iCloud 的 CalDAV 服务无法可靠地支持此功能。
• 发送邮件附件——外发邮件为纯文本。可通过 apple_mail_download_attachment 下载收到的附件。

故障排查

先运行 apple_healthcheck。它会报告每项服务是否已配置凭据（如果没有，指出需要设置哪些变量）、Apple 是否刚刚接受了凭据、当前写入模式以及显示时区。

也可以在终端运行同一项检查，无需 MCP 客户端参与——在将服务接入 Claude 前很有用，也可用于区分凭据问题和客户端问题。它仅读取 shell 环境，不读取 .mcp.json 的 env 块、Claude Desktop 的配置或扩展的设置，因此请先导出相同的值：

printf 'App-specific password: '; read -rs ICLOUD_APP_PASSWORD; echo   # not echoed, kept out of shell history
export ICLOUD_APP_PASSWORD [email protected]
npx -y apple-icloud-mcp doctor                  # every enabled service
npx -y apple-icloud-mcp doctor calendar mail    # only these
npx -y apple-icloud-mcp doctor --json           # the apple_healthcheck report as JSON

当所有已配置的服务都正常工作（且命令行中指定的每项服务都已配置、启用并正常工作）时，它以 0 退出；否则以 1 退出；用法错误时以 2 退出。它会向每项已配置的服务发送一个只读请求（iCloud 服务会逐个发送，因此被撤销的密码只会发送一次），且不会打印任何机密信息。从源码检出目录运行时，node dist/index.js doctor 也会读取仓库的 .env。

症状	可能原因
iCloud“凭据被拒绝”	App 专用密码已被撤销（Apple ID 密码已更改），或使用了普通密码。请生成新的 App 专用密码。
Apple Music 401	开发者密钥有问题：Team ID / Key ID 错误，或密钥不包含 MusicKit。网页模式下：media-user-token cookie 已过期——请复制新的 cookie。
Apple Music 403	Music User Token 已过期（约 6 个月）、由不同的密钥生成，或账户没有 Apple Music 订阅。请重新运行 music-auth（如果没有开发者密钥，请向其所有者索取 music-auth --print-developer-token）。
PLAYLIST_CHANGED	Apple 尚未处理完此服务最近对播放列表所做的更改（读取会比写入延迟数秒），或者播放列表已在其他位置编辑。重新排序、移除曲目、添加重复项检查以及更新播放列表，都会因读取到此类状态而拒绝操作。请使用 apple_music_get_playlist 重新读取后重试。
时间相差数小时	请将 DISPLAY_TZ 设置为你的 IANA 时区。
托管部署中的邮件超时	请检查出站访问许可列表中是否包含 imap.mail.me.com / smtp.mail.me.com。

APPLE_DEBUG_LOG=1 会将每一行上游请求记录到 stderr，并隐藏凭据。

安全

• 凭据在调用时从环境中读取，绝不会写入磁盘、记录到日志或放入 URL； 每条错误和日志信息都会清除进程使用过的所有凭据。

• 只会联系 Apple 的主机；任何指向其他位置的重定向或 DAV href 都会在凭据传出前被拒绝。

• 读取邮件不会将其标记为已读（需要时由 apple_mail_update_flags 执行此操作）。HTML 邮件会转换为纯文本并移除隐藏内容；邮件和日历文本都会标记为来自其发送者的内容。

• 本地数据： $MCP_DATA_DIR/.apple-icloud-mcp/（或 ~/.apple-icloud-mcp/）下的小型文件，权限均为 0600，且都不包含你的密码或令牌：

  • music-web-token.json — Apple Music 网页播放器自己的公开开发者令牌（仅限网页模式）；
  • dav-calendar.json、dav-contacts.json — iCloud 发现 URL，并绑定到提供这些 URL 的凭据；
  • mail-login.json — iCloud 接受的 IMAP 登录表单；
  • icloud-rejected.json — 被拒绝的 Apple ID / 密码组合及其时间的加盐摘要，以便即使重启后也不会在 24 小时内重新发送已撤销的密码；
  • confirm-spent/ — 每个已使用确认令牌对应一个文件（包含其随机 ID 和到期时间），以便重启后也无法重放。托管环境中，如果 MCP_DATA_DIR 为绝对路径，此目录会改为位于 mcp-utils 共享的 $MCP_DATA_DIR/.mcp-confirm/spent/。

  删除该目录即可移除这些文件，或者设置 APPLE_STATE_CACHE=false 以禁止写入这些文件（此时锁存状态和已用令牌记录只在进程运行期间有效，并会发出警告）。

开发

npm run build        # tsc → dist/, then esbuild bundle → dist/bundle.js
npm test             # typecheck + vitest
npm run test:coverage  # 100% line/branch/function/statement coverage is enforced

请参阅 CLAUDE.md 了解架构，并参阅 docs/APPLE-API.md 了解每项 Apple API 详细信息的出处。

许可证

MIT