Apple Books MCP について
Apple Books MCP は、macOS の Apple Books ライブラリに Claude からアクセスできるようにする MCP サーバーです。書籍、読書の進捗、ハイライトやメモを扱えます。自分の読書記録を振り返りたいユーザー向けです。
主な機能
- 01タイトルや著者で書籍を検索
- 02ハイライトとメモの一覧と検索
- 03DRM なし EPUB の章本文の読み取り
- 04現在の読書位置と進捗の確認
- 05ライブラリの概要と読書統計の提供
活用シーン
- 01現在読んでいる章について Claude と議論する
- 02ハイライトをテーマごとに整理して見直す
- 03過去一週間の読書記録とアノテーションを要約する
MCP 対応
このプロジェクトは MCP サーバーとして、ローカルの Apple Books ライブラリデータを読み取るためのツール、リソース、プロンプトを MCP クライアントに提供します。コレクションの編集などの書き込み操作は既定で無効で、明示的に有効にする必要があります。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。
ツール
31掲載時のツール一覧 · 3 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| limit | integer | いいえ | |
| offset | integer | いいえ |
詳細
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
ほかにもさまざまな機能があります!
利用可能なツール
一覧表示ツールと検索ツールは、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_annotation | 1 件の注釈の詳細と、書籍の「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_position | Apple 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が尋ねるのは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_WRITES | off | 1、true、または yes を指定すると、--enable-writes と同様にコレクションの編集が有効になります。 |
APPLE_BOOKS_MCP_THREADS | 8 | 同時に実行するツール呼び出しの数です。0 を指定すると、0.9 より前と同様にサーバーのイベントループ上で一度に1つずつ実行します。値を小さくすると、非常に大きなライブラリでのメモリ使用量も抑えられます。 |
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」という行は、プロセスが起動したことを示すだけで、正常に動作していることを意味するものではありません。~/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 ファイルをご覧ください。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。