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	1つの注釈の詳細を取得します。色を含みます。
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 は色を返しますが、一度に1件ずつのため、1冊の書籍に対して150回以上呼び出す必要があります。

解決策： 色ごとに get_highlights_by_color を1回ずつ（合計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 を5回呼び出し → 色マップを作成します
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	ハイライトではなくブックマークです	これらを除外します