mcpField
A
Apple Books MCP

Apple Books MCP

ローカル
vgnshiyer.meゲーム・エンタメ643 週間前に更新

Apple Books MCP について

Apple Books MCP は、macOS の Apple Books ライブラリに Claude からアクセスできるようにする MCP サーバーです。書籍、読書の進捗、ハイライトやメモを扱えます。自分の読書記録を振り返りたいユーザー向けです。

主な機能

  1. 01タイトルや著者で書籍を検索
  2. 02ハイライトとメモの一覧と検索
  3. 03DRM なし EPUB の章本文の読み取り
  4. 04現在の読書位置と進捗の確認
  5. 05ライブラリの概要と読書統計の提供

活用シーン

  1. 01現在読んでいる章について Claude と議論する
  2. 02ハイライトをテーマごとに整理して見直す
  3. 03過去一週間の読書記録とアノテーションを要約する

MCP 対応

このプロジェクトは MCP サーバーとして、ローカルの Apple Books ライブラリデータを読み取るためのツール、リソース、プロンプトを MCP クライアントに提供します。コレクションの編集などの書き込み操作は既定で無効で、明示的に有効にする必要があります。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ
パッケージ
pypiapple-books-mcp0.9.0
mcpbapple-books-mcp-0.9.0.mcpb0.9.0

ツール

31

掲載時のツール一覧 · 3 週間前に更新

パラメーター型必須説明
limitintegerいいえ
offsetintegerいいえ

詳細

Apple Books MCP

Apple Books 用の Model Context Protocol(MCP)サーバーです。

Website MCP Server PyPI License: Apache 2.0 README の画像 Buy Me A Coffee

概要

  • 前回の続きから読み始める — Claude は、読んでいる本、読書の進捗、現在の章を確認し、必要に応じてその章のテキスト(chapter_id="current")とハイライトを取得します。
  • あらゆる本を検索する — 大文字・小文字、アクセント記号、曲線引用符を区別せず、タイトルまたは著者名で検索できます。Apple Books で本を開くリンクも表示されます。
  • ハイライトの内容を掘り下げる — 前後の段落を文脈に沿って説明し、マークした箇所を «...» で正確に表示します。
  • 本を読み返す — ハイライトを取得してテーマごとに分類し、あなた自身の言葉を引用してもらえます。
  • 読書を振り返る — 複数の本にまたがるパターン、ハイライトに繰り返し現れるアイデア、実際に惹かれているものを確認できます。

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

ほかにもさまざまな機能があります!

利用可能なツール

一覧表示ツールと検索ツールは、1 ページずつ結果を返します。デフォルトでは注釈を 50 件、本を 200 冊表示します。limit は 1~500 の範囲で指定でき、次のページを取得するには offset を指定します。続きがある場合は出力にその旨が示され、次の offset が表示されます。

結果の仕組み:

  • ID は整数です。各行は [175] Title by Author のように ID で始まり、book_id、annotation_id、collection_id として渡せます。"175" のような数値文字列も受け付けますが、true、false、小数は ID として使えません。
  • 失敗(不明な ID、ダウンロードされていない本、不正な color)は、次に行う操作(多くの場合、呼び出す別のツール)を示すメッセージを含む MCP エラー(isError)として返されます。空の結果(「No books matched …」)は正常な応答であり、エラーではありません。
  • 本から取得したテキスト(章の本文、ハイライト前後の文章、目次、本の説明)は <book_text>…</book_text> で囲まれます。サーバーの指示により、Claude はこのテキストを本からの信頼できないデータとして扱い、指示として従わないようになっています。
  • ライブラリから削除した本のハイライトは Apple Books に保持されます。ライブラリに残っている本の後に、「削除した本(asset 3F2A1B2C…)」として、本ごとに表示されます。
コレクション
ツール説明パラメーター
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 には、章関連ツールで本を読めるかどうか、読めない場合はその理由を示す Readable text 行があります。表示される理由は、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_annotation1 件の注釈の詳細と、書籍の「Books で開く」リンクを取得します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_positionApple Books の自動ブックマーク CFI に基づいて、ユーザーが最後に読んでいた章を取得し、「Books で開く」リンクを表示しますbook_id: int

利用可能なリソース

Claude Desktop のリソースピッカーからアクセスできる、添付可能なデータオブジェクトです。

リソースURI説明
読書中の書籍apple-books://currently-reading現在読んでいる書籍(最近開いた、読みかけの書籍)のタイトル、著者、書籍 ID、進捗状況、「Books で開く」リンク、読み終えた位置の章とその章 ID(DRM なしの EPUB の場合。それ以外では、テキストを読み取れない理由)、およびその書籍のハイライト数を示す簡単な案内です。章のテキストやハイライトは含まれません。Claude は必要に応じて get_chapter_content と list_annotations で取得します。会話に添付すると、Claude が現在読んでいる書籍に焦点を合わせられます。

利用可能なプロンプト

Claude Desktop のプロンプトピッカーから利用できる、ワンクリックのワークフローです。

プロンプト説明引数
weekly_digest過去 1 週間に読んだ内容とハイライトした箇所を要約します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 が待つ時間とほぼ同じく、最大 1 分かかることがあります。上記のコマンドを Terminal で一度実行すると、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 をダウンロードしてダブルクリックするか、Settings → Extensions → Install Extension… を開いてファイルを選択し、Install をクリックします。uv とロックされた依存関係は Desktop が自動でインストールします。拡張機能の設定で コレクションの編集を許可すると、--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 で標準入力を開いたままにしてください。イメージは非特権ユーザーとして実行され、以前と同じマウントパスからライブラリを読み取ります。

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)

サーバーがライブラリを初めて読み取るとき、Apple Booksはライブラリを独自のアプリコンテナ(~/Library/Containers/com.apple.iBooksX/)に保存しているため、macOSはプログラムに「ほかのアプリのデータへのアクセス」を許可するかどうかを尋ねます。許可をクリックしてください。

macOSのアクセス許可プロンプト:「uvx」がほかのアプリのデータへのアクセスを求めています。「許可しない」/「許可」。

macOSが尋ねるのはapple-books-mcp自体についてではなく、Claudeが起動するプログラムについてです。

  • 推奨されるClaude Desktopの設定ではuvx(上のプロンプト);
  • pipの設定ではPythonインタープリター;
  • サーバーをClaude Codeに設定している場合はclaude;
  • サーバーを手動で実行する場合はターミナルアプリ。

アクセス許可はそのプログラムに付与されるため、そのプログラムが起動するほかのプログラムも利用できます。apple-books-mcpはライブラリと、章のテキストを取得するための書籍ファイルのみを読み取ります。--enable-writesを渡さない限り、何も変更しません。

確認するには、ターミナルでuvx apple-books-mcp --doctorを実行します。実行中のプログラムがライブラリを読み取れるかどうかを報告し、読み取れない場合は修正方法を示します。このコマンドを実行すると、ターミナルアプリのアクセス許可を確認します。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

これにより、すべてのアプリに対する「ほかのアプリのデータ」へのアクセス許可の決定がリセットされます。その後、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分以上古い場合にPyPIを確認します。通常、Claudeの起動時にはこの条件に当てはまります。apple-books-mcp@latestを指定しても利点はなく、起動するたびにuvが新しい環境を構築するため、約1秒ではなく3~12秒かかります。

起動の高速化、またはオフラインでの起動

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を使用する

Using pipで作成した仮想環境内のスクリプトをClaudeに指定し、ホームディレクトリを省略せずに記述してください。

{
    "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_WRITESoff1、true、または yes を指定すると、--enable-writes と同様にコレクションの編集が有効になります。
APPLE_BOOKS_MCP_THREADS8同時に実行するツール呼び出しの数です。0 を指定すると、0.9 より前と同様にサーバーのイベントループ上で一度に1つずつ実行します。値を小さくすると、非常に大きなライブラリでのメモリ使用量も抑えられます。
APPLE_BOOKS_DATA_DIRApple Books 独自のフォルダー読み取り対象の Apple Books の Documents フォルダーです(BKLibrary/ と AEAnnotation/ が含まれるフォルダー)。
APPLE_BOOKS_QUERY_TIMEOUT30ライブラリのクエリを停止するまでの秒数です。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」という行は、プロセスが起動したことを示すだけで、正常に動作していることを意味するものではありません。
  • ~/Library/Logs/Claude/main.log には、Desktop の Claude Code または Cowork のセッションでツールが読み込まれた際に、「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」:この macOS ユーザー用のライブラリが Apple Books にまだ作成されていません。Books を一度開いてから、再試行してください。
  • ツールの実行中に応答を停止する場合:0.9 以降では、停止されたツール呼び出しにはすぐに応答し、サーバーはほかのセッションへのサービスを続けます。呼び出しの残りの処理はバックグラウンドで完了します(すでに開始していた書き込みは完了し、まだ開始していなかった書き込みは実行されません)。
  • main.log に表示される 「Extension apple-books-mcp not found in installed extensions」 は無視して問題ありません。
Claude に再試行させる
  • Claude Desktop のチャット:Claude を完全に終了(Cmd+Q)して、再度開いてください。起動に失敗したサーバーは、それ以外の方法では再試行されません。
  • Desktop の Claude Code と 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 に公開します。

デバッグ

ログは stderr に出力され、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"
            ]
        }
    }
}

インスペクターを使用する場合

npx @modelcontextprotocol/inspector uv --directory /path/to/apple-books-mcp run apple-books-mcp
Issue の作成

バグを見つけた場合、機能をリクエストしたい場合、またはプロジェクトに関連する内容について話し合いたい場合は、GitHub リポジトリで Issue を作成してください。Issue を作成する際は、次の情報を記載してください:

バグ報告:問題を詳しく説明してください。可能であれば、エラーメッセージやスクリーンショットとともに、バグを再現する手順を記載してください。

機能リクエスト:プロジェクトに追加してほしい新機能を明確に説明してください。その機能が役立つ理由も記載してください。

一般的な議論:プロジェクトに関連する幅広いトピックについて、気軽に議論を始めてください。

コントリビューション

1️⃣ 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 ファイルをご覧ください。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。