Apple Books MCP

Apple Books MCP

Apple Books 的 Model Context Protocol（MCP）服务。

概览

• 从上次阅读处继续 — Claude 可以看到你正在读的书、阅读进度和当前章节，并在需要时获取该章节的文本（chapter_id="current"）及你的高亮。
• 查找任意图书 — 可按书名或作者搜索，不区分大小写、重音符号和弯引号，并提供可在 Apple Books 中打开图书的链接。
• 深入了解任意高亮 — 获取高亮所在段落的上下文解释，并用 «...» 显示你标记的确切文本。
• 重温一本书 — 获取你的高亮，按主题归类，并引用你自己的摘录。
• 反思阅读体验 — 探索不同图书之间的模式、高亮中反复出现的观点，以及真正吸引你的内容。

https://github.com/user-attachments/assets/77a5a29b-bfd7-4275-a4af-8d6c51a4527e

还有更多功能！

可用工具

列表和搜索工具每次返回一页：默认包含 50 条批注或 200 本图书，limit 取值范围为 1 到 500，使用 offset 获取下一页。有更多结果时，输出会提示并给出下一个 offset。

结果说明：

• ID 为整数：每一行都以 ID 开头，例如 [175] Title by Author，可将其作为 book_id、annotation_id 或 collection_id 传入。也接受 "175" 这样的数字字符串；true、false 和小数都不是 ID。
• 发生失败时（ID 未知、图书尚未下载或 color 无效），会返回 MCP 错误（isError），其消息会说明下一步该怎么做，通常会提示调用另一个工具。空结果（“No books matched …”）属于正常响应，不是错误。
• 从图书中提取的文本（章节文本、高亮周围的段落、目录、图书简介）会用 <book_text>…</book_text> 包裹。服务的指令会告知 Claude，这些文本是来自图书的不可信数据，绝不是需要遵循的指令。
• 从资料库中移除的图书，其高亮会由 Apple Books 保留。这些高亮会按已移除的图书分别显示为“Removed book (asset 3F2A1B2C…)”，并列在仍在资料库中的图书之后。

合集

Tool	Description	Parameters
list_all_collections	列出所有合集	limit?: int（默认值：200），offset?: int
get_collection_books	获取合集中的所有图书	collection_id: int
describe_collection	获取合集详情	collection_id: int
search_collections_by_title	按标题搜索合集	title: str

编辑合集（自选启用）

默认关闭。向服务器参数添加 --enable-writes 即可启用：

"args": ["apple-books-mcp", "--enable-writes"]

使用 Claude Desktop 扩展 时，请改为在扩展设置中开启 允许编辑合集。

Apple 未提供用于自动化合集的 API，因此这些操作会直接写入图书馆数据库，但设有防护措施：Books 打开时，所有写入操作都会被拒绝；操作前会自动创建兼容 WAL 的备份（~/.py_apple_books/backups/）；会验证架构，发现架构变更时中止；并且只会修改用户创建的合集（以及“想读”合集的成员关系）。删除合集不会删除其中的图书。

⚠️ 如果已启用 iCloud 合集同步，直接编辑可能不会同步到其他设备，也可能在云端重新同步时被还原。

工具	描述	参数
create_collection	创建新合集	title: str, details?: str
rename_collection	重命名用户创建的合集	collection_id: int, new_title: str
delete_collection	删除用户创建的合集（不影响图书）	collection_id: int
add_book_to_collection	将图书添加到合集（幂等）	collection_id: int, book_id: int
remove_book_from_collection	从合集中移除图书（幂等）	collection_id: int, book_id: int

图书

工具	描述	参数
list_all_books	列出所有图书	limit?: int (default: 200), offset?: int
search_books	查找标题或作者包含查询内容的图书，不区分大小写、重音符号及引号或破折号样式	query: str, limit?: int (default: 200), offset?: int
search_books_by_title	按标题搜索图书（匹配方式相同，仅搜索标题）	title: str, limit?: int (default: 200), offset?: int
describe_book	获取特定图书的详细信息（元数据、阅读进度、批注数量、简介）、文本是否可读（见下文），以及“在 Books 中打开”链接	book_id: int
list_annotations	按阅读顺序列出图书的批注（每行包含 id、文本和章节，以及你的笔记）	book_id: int, limit?: int (default: 50), offset?: int
get_books_by_genre	按类型获取图书（子字符串匹配）	genre: str, limit?: int (default: 200), offset?: int

describe_book 会显示 文本可读性 一行，说明章节工具是否能读取图书；如果不能，也会说明原因：yes (EPUB)、PDF、受 DRM 保护、尚未下载（仅存于 iCloud、属于 Apple Books Store 的书籍，或从未下载），或文件缺失。此信息根据图书馆记录和文件元数据得出，不会打开图书：读取仅存于 iCloud 的文件会导致 macOS 下载该文件。

“在 Books 中打开”链接（ibooks://assetid/…）会在 Apple Books 中打开图书。此类链接会出现在 describe_book、describe_annotation、get_current_reading_position 和“正在阅读”资源中。

阅读状态

工具	描述	参数
get_books_in_progress	获取正在阅读的图书	limit?: int (default: 200), offset?: int
get_finished_books	获取已读完的图书	limit?: int (default: 200), offset?: int
get_unstarted_books	获取尚未开始阅读的图书	limit?: int (default: 200), offset?: int
get_recently_read_books	获取最近阅读的图书	limit?: int (default: 10), offset?: int

注释

工具	描述	参数
list_all_annotations	按图书分组浏览所有注释，按时间从新到旧排列，并显示你的笔记	limit?: int (默认：50), offset?: int
recent_annotations	获取最近的注释（平铺显示，每行包含日期和图书）	limit?: int (默认：10), offset?: int
describe_annotation	获取单条注释的完整详情，并附上图书的“在图书中打开”链接	annotation_id: int
get_annotation_context	获取高亮内容周围的文本（所在段落），并用 «...» 标记高亮内容	annotation_id: int, chars_before?: int (默认：500), chars_after?: int (默认：500)
get_highlights_by_color	按图书分组获取特定颜色的高亮内容	color: yellow|green|blue|pink|purple, limit?: int (默认：50), offset?: int, order_by?: newest|oldest
search_notes	搜索用户笔记（行内显示高亮内容和笔记）	note: str, limit?: int (默认：50), offset?: int, order_by?: newest|oldest
search_annotations	搜索高亮内容、笔记和周围文本（行内显示笔记）	text: str, limit?: int (默认：50), offset?: int, order_by?: newest|oldest
get_annotations_by_date_range	获取日期范围内的注释，包含 before 当天，使用本地时间（平铺显示，每行包含日期和图书）	after?: YYYY-MM-DD, before?: YYYY-MM-DD, limit?: int (默认：50), offset?: int, order_by?: newest|oldest

图书馆统计

工具	描述	参数
get_library_stats	获取包含阅读统计数据的图书馆摘要	无

图书内容

仅适用于下载到这台 Mac 上的非 DRM EPUB（导入的图书、Project Gutenberg、Standard Ebooks 等）。Apple Books Store 购买的图书通常受 FairPlay 保护，会返回明确的错误；仅存储在 iCloud 中的图书会提示“尚未下载”；describe_book 中的“可阅读文本”行会提前说明。

工具	描述	参数
list_book_chapters	查看图书目录（章节标题、顺序和嵌套关系）	book_id: int
get_chapter_content	获取章节的纯文本内容，可选使用 offset 和 max_chars 进行切片。chapter_id="current"（默认值）会读取你在 Apple Books 中正在阅读的章节	book_id: int, chapter_id?: str (默认："current"), offset?: int, max_chars?: int
get_current_reading_position	获取用户上次阅读到的章节（通过 Apple Books 的自动书签 CFI），并附上“在图书中打开”链接	book_id: int

可用资源

可通过 Claude Desktop 的资源选择器访问并附加的数据对象。

资源	URI	描述
正在阅读	apple-books://currently-reading	简要介绍你当前正在阅读的图书（最近打开且尚未读完的图书）：标题、作者、图书 ID、阅读进度、“在图书中打开”链接、上次读到的章节及其章节 ID（适用于非 DRM EPUB；否则会说明无法读取文本的原因），以及该图书的高亮数量。此资源不包含章节文本或高亮内容；Claude 会根据需要通过 get_chapter_content 和 list_annotations 获取这些内容。将其附加到任意对话中，即可让 Claude 聚焦于你当前正在读的内容。

可用提示词

可从 Claude Desktop 的提示词选择器访问的一键工作流。

提示词	描述	参数
weekly_digest	总结我过去一周的阅读和高亮内容	days?: int (默认：7)
library_snapshot	回顾我的整个阅读历程	无
revisit_book	重温特定图书中的笔记和高亮内容	book_title: str

安装

要求

• macOS，且至少打开过一次 Apple Books（它会创建此服务要读取的图书馆）。
• Python 3.10 或更高版本。uvx 和 Claude Desktop 扩展会在需要时提供该版本。
• 随服务安装：mcp >= 1.12 (< 2) 和 py-apple-books >= 1.10 (< 2)。

使用 uv（推荐）

uvx 无需单独安装步骤，即可运行 apple-books-mcp。

brew install uv  # for macos
uvx apple-books-mcp --version

首次运行会下载约 14 MB 的依赖项，可能需要一分钟，这与 Claude 等待服务启动的时间相近。在将服务添加到 Claude 之前，先在终端中运行一次上述命令，即可预热 uv 的缓存。--version 会显示 uvx 解析出的 apple-books-mcp、mcp 和 py-apple-books 版本。

然后通过下方的 JSON 配置 或 Claude Code 命令 将服务添加到 Claude。

Claude Desktop 扩展（.mcpb）

Claude Desktop 也可以将 apple-books-mcp 安装为扩展，无需编辑其配置：从最新的 GitHub 版本发布页下载 apple-books-mcp-<version>.mcpb，双击该文件（或打开“设置” → “扩展” → “安装扩展…”，然后选择该文件），再点击安装。Desktop 会自行安装 uv 和锁定的依赖项。扩展设置中的允许编辑合集与 --enable-writes 的作用相同。

对于由组织管理的 Claude（Team/Enterprise），管理员可以将 Desktop Extensions 限制为许可名单，或将其关闭。如果 .mcpb 安装遭到拒绝，请使用下方的 JSON 配置。如果策略也禁用了用户添加的 MCP 服务，请让管理员批准该扩展。

使用 pip

需要 Python 3.10 或更高版本（macOS 随附的 python3 为 3.9）。请安装到虚拟环境中：

python3 -m venv ~/.venvs/apple-books-mcp
~/.venvs/apple-books-mcp/bin/pip install apple-books-mcp
~/.venvs/apple-books-mcp/bin/apple-books-mcp --version

之后可使用 ~/.venvs/apple-books-mcp/bin/pip install -U apple-books-mcp 进行升级。

使用 Docker（已弃用）

⚠️ Docker 镜像已弃用，且只能部分正常工作：Linux 容器无法获得 macOS 权限，无法访问存储在 iCloud Drive 中的图书文件（因此读取图书文本的工具会失败），也无法判断 Books 是否正在运行（因此不支持写入合集）。请改用 uvx。

它仍可提供书库元数据和注释。以只读方式挂载 Apple Books 容器，并使用 -i 保持 stdin 打开。该镜像以非特权用户身份运行，并从与之前相同的挂载路径读取书库：

docker run -i --rm -v ~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro ghcr.io/vgnshiyer/apple-books-mcp:latest

在 Claude 配置中，请写出完整的主目录路径：Claude 不会展开 ~。

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-v", "/Users/YOU/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro",
                "ghcr.io/vgnshiyer/apple-books-mcp:latest"
            ]
        }
    }
}

首次运行时的权限提示（macOS）

服务器首次读取你的资料库时，macOS 会询问是否允许启动它的程序“访问其他 App 中的数据”，因为 Apple Books 将其资料库存放在自己的 App 容器中（~/Library/Containers/com.apple.iBooksX/）。点击 允许。

macOS 询问的是 Claude 启动的程序，而不是 apple-books-mcp 本身：

• 使用推荐的 Claude Desktop 配置时，是 uvx（如上方提示所示）；
• 使用 pip 配置时，是 Python 解释器；
• 在 Claude Code 中配置服务器时，是 claude；
• 手动运行服务器时，是你的终端 App。

权限属于该程序，因此它启动的其他程序也能使用此权限。apple-books-mcp 只会读取资料库，以及用于获取章节文本的图书文件；除非你传入 --enable-writes，否则不会更改任何内容。

若要检查，请在终端中运行 uvx apple-books-mcp --doctor：它会报告运行该命令的程序是否可以读取资料库；如果不能，还会说明如何修复。以这种方式运行时，检查的是终端 App 的权限；macOS 会单独询问此权限，与 uvx 或 Claude 的权限无关。

更新后又被询问？ Homebrew 的 uv/uvx，以及 Homebrew 或 uv 管理的 Python 构建版本，均未由已注册的开发者签名，因此在运行 brew upgrade uv（或升级 Python）后，macOS 会将其视为新程序并再次询问。点击 允许。

点击了“不允许”？ 随后工具会报错：“macOS denied access to the Apple Books library”。（旧版则会在启动时直接失败，并显示：“No sqlite files found in … Please open Apple Books at least once”。）“系统设置”中没有此权限的开关。若要再次看到提示，请运行：

tccutil reset SystemPolicyAppData

这会清除所有 App 的“其他 App 中的数据”访问决定。然后退出并重新打开 Claude，再点击 允许。也可以在“系统设置”>“隐私与安全性”> 完全磁盘访问权限中添加该程序（例如 /opt/homebrew/bin/uvx），但这样会授予更多权限。

配置

Claude Desktop 设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 前，请先退出 Claude Desktop（Cmd+Q）：Desktop 运行期间会重写该文件，因此在它打开时所做的编辑可能会丢失。

使用 uvx（推荐）

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uvx",
            "args": [ "apple-books-mcp" ]
        }
    }
}

直接使用 apple-books-mcp 仍然可以获取新版本：只要 uv 缓存的软件包索引超过 10 分钟，uv 就会检查 PyPI 是否有更新版本；Claude 启动时通常已经超过 10 分钟。使用 apple-books-mcp@latest 没有任何额外好处，还会导致 uv 在每次启动时都构建一个全新的环境（耗时 3–12 秒，而非约 1 秒）。

更快或离线启动

由于 uvx 会在启动时检查 PyPI，因此 PyPI 无法访问时，服务器将无法启动。若要避免这种情况：

• 运行一次 uv tool install apple-books-mcp。相同的 uvx 配置随后会使用已安装的副本，无需连接 PyPI，约 1 秒即可启动。已安装的副本不会自动更新：运行 uv tool upgrade apple-books-mcp 以获取新版本。
• 或使用 "args": ["--offline", "apple-books-mcp"]，运行 uv 已缓存的版本（至少在线运行过一次后即可），且无需联网。

使用 pip

将 Claude 指向 使用 pip 中虚拟环境里的脚本，并写明你的主目录完整路径：

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "/Users/YOU/.venvs/apple-books-mcp/bin/apple-books-mcp"
        }
    }
}

Claude Code 设置

Claude Code 不会读取 Claude Desktop 配置。使用以下命令添加服务器：

claude mcp add --scope user apple-books-mcp -- uvx apple-books-mcp

并使用 /mcp 检查。

环境变量

在 Claude 配置中服务器的 "env" 里设置这些变量（例如，在 "args" 旁边设置 "env": {"APPLE_BOOKS_MCP_THREADS": "4"}），也可以使用 claude mcp add -e NAME=value。

变量	默认值	作用
APPLE_BOOKS_MCP_ENABLE_WRITES	关闭	设置为 1、true 或 yes 可启用收藏集编辑，相当于 --enable-writes。
APPLE_BOOKS_MCP_THREADS	8	同时运行的工具调用数量。设置为 0 时，工具调用会像 0.9 之前一样在服务器的事件循环中逐个运行。较低的值也能限制超大型书库占用的内存。
APPLE_BOOKS_DATA_DIR	Apple Books 自己的文件夹	要读取的 Apple Books Documents 文件夹（其中包含 BKLibrary/ 和 AEAnnotation/）。
APPLE_BOOKS_QUERY_TIMEOUT	30	图书馆查询可运行的秒数，超过后将停止；0 表示不设限制。

故障排除

查看位置

• 在终端中运行 uvx apple-books-mcp --doctor 可检查版本、查找书库、说明 macOS 权限问题，并显示已读取数据的计数。该命令只读取数据，不会打印书名或文本。
• ~/Library/Logs/Claude/mcp-server-apple-books-mcp.log（名称取自你的 mcpServers 键）包含服务器自身的输出，包括 Python 回溯。如需更多详情，可在参数中添加 "-v"：服务器随后会记录其版本、所用的 mcp 和 py-apple-books 版本，以及每个请求。
• ~/Library/Logs/Claude/mcp.log 会列出失败记录。其中的 “Server started and connected successfully” 只表示进程已启动，并不表示服务器正常工作。
• 当 Claude Code 或 Cowork 会话在 Desktop 中加载工具时，~/Library/Logs/Claude/main.log 会记录 “Connected to apple-books-mcp (N tools)”。
• 在终端中运行 uvx apple-books-mcp --version 可查看 uvx 解析出的版本。

常见问题

• “Connection closed”、“Server disconnected” 或 “Server transport closed unexpectedly”：服务器在启动时退出了。请查看 mcp-server-apple-books-mcp.log 中回溯记录的最后一条错误。
  • No module named 'mcp.server.fastmcp'：uv 选择了早于 0.8.1 的 apple-books-mcp 版本，并搭配 mcp 2.x；mcp 2.x 移除了这些版本所依赖的 API（在 Python 3.12 及更早版本中，uvx 甚至可能回退到 0.1.2）。0.8.1 及更高版本兼容 Python 3.10+，并使用 mcp 1.x。运行 uv cache clean apple-books-mcp，检查 uvx apple-books-mcp --version 是否显示 0.8.1 或更高版本，然后退出并重新打开 Claude。
  • 真正错误之前出现的 No module named 'server' 错误是 0.8.4 之前版本产生的无关信息。
• 启动时出现“Not ready after 60 seconds”或“Request timed out”：首次启动时仍在下载和安装依赖。在终端中运行一次 uvx apple-books-mcp --version，然后重新打开 Claude。
• “macOS denied access to the Apple Books library”（旧版本显示：“No sqlite files found in …”）：请参阅首次运行时的权限提示。
• “No Apple Books library store found”：Apple Books 尚未为当前 macOS 用户创建书库。打开一次“图书”应用，然后重试。
• 工具运行时停止响应：从 0.9 起，停止的工具调用会立即返回响应，服务器会继续为其他会话提供服务；该调用剩余的工作会在后台完成（已开始的写入仍会完成；尚未开始的写入则不会运行）。
• main.log 中的 “Extension apple-books-mcp not found in installed extensions” 可以忽略。

让 Claude 重试

• Claude Desktop 聊天：完全退出 Claude（Cmd+Q），然后重新打开。否则，启动失败的服务器不会重试。
• Claude Code 和 Desktop 中的 Cowork 会话：启动新会话；每个新会话都会重试服务器。
• Claude Code：运行 /mcp 并重新连接 apple-books-mcp，或重启 Claude Code。

即将推出的功能

• 高亮导出：按阅读顺序导出书籍的高亮和笔记，并附带章节标题
• 在 1.0 版本中精简为数量更少、范围更广的工具，目前有多个工具功能重叠
• 对于已移除的书籍，在 Apple Books 缓存仍保留其信息时显示书名
• PDF 内容访问（目前仅支持 EPUB）

贡献

感谢您考虑为本项目做出贡献！

开发

克隆仓库，然后让 uv 创建虚拟环境并安装软件包及其依赖项：

uv sync
uv run apple-books-mcp --version
uv run pytest

要在本地构建 Claude Desktop 扩展，请先安装固定版本的打包工具，然后进行构建：

npm ci --ignore-scripts --prefix mcpb
uv run python scripts/build_mcpb.py

这会生成 dist/apple-books-mcp-<version>.mcpb 和注册表的 dist/server.json（--out DIR 可指定其他文件夹）。python scripts/build_mcpb.py --smoke dist/apple-books-mcp-<version>.mcpb 会按照 Claude Desktop 的方式安装该程序包，并检查启动的服务。

维护者：发布 GitHub 版本会运行发布工作流，该工作流会检查标签与每个版本字段是否一致、发布到 PyPI、将 .mcpb 附加到版本发布中，并发布到 MCP Registry。

调试

日志会输出到标准错误流，Claude Desktop 会将其写入 ~/Library/Logs/Claude/mcp-server-<name>.log。不带标志时，服务只记录警告和错误；-v 会添加启动详情（版本、是否启用写入）和每个请求的一行日志；-vv 会添加 MCP SDK 的调试输出。

使用 Claude Desktop

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/apple-books-mcp/",
                "run",
                "apple-books-mcp",
                "-v"
            ]
        }
    }
}

使用 inspector

npx @modelcontextprotocol/inspector uv --directory /path/to/apple-books-mcp run apple-books-mcp

提交问题

如果您遇到错误、有功能请求，或想讨论与项目相关的事项，请在 GitHub 仓库中提交问题。提交问题时，请提供以下信息：

错误报告：详细描述问题。如果可能，请提供复现步骤，以及任何错误消息或截图。

功能请求：清楚说明您希望为项目添加的功能，并介绍该功能为何有帮助。

一般讨论：欢迎就与项目相关的更广泛话题发起讨论。

贡献方式

1️⃣ Fork GitHub 仓库 https://github.com/vgnshiyer/apple-books-mcp
2️⃣ 为您的更改创建一个新分支（git checkout -b feature/my-new-feature）。
3️⃣ 进行更改并充分测试。
4️⃣ 推送更改，并向 main 发起 Pull Request。

请为您的更改提供清晰的标题和说明。

许可证

Apple Books MCP 基于 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。