apple-books-mcp

Apple Books MCP

MCP 服务：vgnshiyer/apple-books-mcp

安装：npx -y @anthropic-ai/claude-code mcp add apple-books -- uvx apple-books-mcp

工具参考

工具	用途
list_all_books	列出所有图书（ID、标题、作者）
get_book_annotations	获取指定 ID 图书的所有批注。不含颜色数据。
describe_annotation	获取单条批注的完整详情，包括颜色
get_highlights_by_color	获取整个书库中所有指定颜色的高亮内容
search_highlighted_text	按高亮文本搜索批注
search_notes	按用户撰写的笔记搜索
list_all_annotations	获取所有图书中的全部批注
list_all_collections	列出所有合集
get_collection_books	获取合集中的图书
describe_book / describe_collection	按 ID 获取详情
recent_annotations	获取最近创建的批注
full_text_search	在所有图书中进行全文搜索

重要：颜色提取策略

get_book_annotations 不会返回颜色。describe_annotation 会返回颜色，但一次只能查询一条批注——单本图书就需要调用 150 次以上。

**解决方案：**每种颜色调用一次 get_highlights_by_color（总共调用 5 次），然后以编程方式交叉匹配批注 ID。

Available colors: PINK, BLUE, YELLOW, GREEN, PURPLE
Underlines: color = null, is_underline = 1

构建颜色映射

import json, glob

# After calling get_highlights_by_color for PINK, BLUE, YELLOW, GREEN, PURPLE
# Results save to files when they exceed token limits

ann_color = {}
colors = ["PINK", "BLUE", "YELLOW", "GREEN", "PURPLE"]

for color_file, color in zip(sorted(glob.glob("path/to/results/*.txt")), colors):
    with open(color_file, 'r') as f:
        data = json.load(f)
    current_id = None
    for line in data.get("text", "").split("\n"):
        line = line.strip()
        if line.startswith("ID: "):
            current_id = line.split("ID: ")[1].strip()
        elif line.startswith("Selected text: ") and current_id:
            selected = line[len("Selected text: "):]
            if selected and selected != "None":
                ann_color[current_id] = color

# Look up: ann_color.get(str(annotation_id), None)  # None = underline

工作流：提取图书列表中的高亮内容

第 1 步：匹配图书

调用 list_all_books 并与用户的列表进行匹配。提示：

• 图书可能以译名显示（例如，俄语版本）
• PDF 的标题往往乱码或以文件名命名
• 使用部分匹配或模糊匹配——“Vignelli Canon”可能只显示为“canon”
• 同一本书可能有多个版本（ID 不同）

第 2 步：获取每本图书的批注

get_book_annotations(book_id="531")

返回：ID、selected_text、representative_text、note、chapter、location、修改日期。过滤掉 selected_text 为 None 的条目（空书签）。

第 3 步：获取颜色（批量）

get_highlights_by_color(color="PINK")
get_highlights_by_color(color="BLUE")
get_highlights_by_color(color="YELLOW")
get_highlights_by_color(color="GREEN")
get_highlights_by_color(color="PURPLE")

结果很大（100k-400k 个字符）。使用 Python 解析。

第 4 步：导出为 Markdown

color_emoji = {
    "PINK": "🩷", "BLUE": "🔵", "YELLOW": "🟡",
    "GREEN": "🟢", "PURPLE": "🟣",
}

lines = [f"# {title}", f"**{author}**", "", "---", ""]
for ann_id, text in annotations:
    color = ann_color.get(str(ann_id), None)
    tag = color_emoji.get(color, "〰️")  # 〰️ for underlines
    lines.append(f"{tag} {text}")
    lines.append("")

批注数据结构

来自 describe_annotation：

{
  "id": 2133,
  "selected_text": "be impeccable with your word",
  "representative_text": "The first agreement is to be impeccable...",
  "note": null,
  "is_underline": 0,
  "style": 4,
  "color": "PINK",
  "chapter": null,
  "location": "epubcfi(/6/12[c005]!/4/10,/1:26,/2/1:28)"
}

样式与颜色的对应关系

样式	颜色
0	下划线（无颜色）
1	绿色
2	蓝色
3	黄色
4	粉色
5	紫色

示例

示例 1：导出阅读清单中的所有高亮内容

用户说：“提取我的阅读清单中图书的高亮内容”

1. 读取用户的列表（文件、笔记等），获取图书标题
2. list_all_books → 将标题与 ID 匹配
3. 对每本匹配的图书：get_book_annotations(book_id=ID) → 收集批注 ID 和文本
4. get_highlights_by_color x5 → 构建颜色映射
5. Python 脚本合并批注和颜色 → 为每本图书写入 .md 文件

示例 2：搜索所有图书中的引文

用户说：“查找我标记过的关于影子工作的内容”

1. search_highlighted_text(text="shadow") → 返回匹配的批注及图书上下文
2. 如果需要颜色：对少量结果调用 describe_annotation(annotation_id=ID)

示例 3：获取所有粉色高亮内容

用户说：“显示我所有粉色的高亮内容”

1. get_highlights_by_color(color="PINK") → 获取整个书库中的所有粉色高亮内容
2. 按图书标题分组，便于阅读

故障排除

问题现象	原因	解决方法
list_all_books 为空	从未打开过 Apple Books	打开一次 Apple Books 应用
图书没有批注	读过图书，但没有标记高亮	这是预期行为
describe_annotation 的颜色为 null	这是下划线	检查 is_underline 字段
颜色结果过大	书库中的高亮内容很多	结果会自动保存到文件；使用 Python 解析
图书标题不匹配	版本或译本不同	尝试作者名或部分标题
selected_text 为 None	这是书签，不是高亮内容	过滤掉这些条目