calibre-mcp について
calibre-mcpは、MCPクライアントをCalibreの電子書籍ライブラリに接続し、検索、閲覧、メタデータ整理を行うサーバーです。セマンティック検索とキーワード検索を組み合わせ、書き込みは明示的な有効化と確認で制御します。
主な機能
- 01セマンティック・キーワード混合検索
- 02ライブラリ全体または書籍内検索
- 03本文と図の取得
- 04メタデータの監査と整理
- 05有効化と確認が必要な書き込み
活用シーン
- 01電子書籍ライブラリから関連箇所を検索
- 02タイトルではなく概念から章を特定
- 03重複書籍の検出とメタデータ修正
- 04確認付きの一括メタデータ変更
MCP 対応
このサーバーは、Calibreライブラリの検索、閲覧、整理に使う19種類のツールをMCPクライアントに公開します。書き込みツールは初期状態で無効で、明示的なゲート設定が必要です。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
npx -y calibre-mcpCALIBRE_MCP_SERVER_URLCalibre Content Server base URL (default http://localhost:8080)CALIBRE_MCP_LIBRARYLibrary name; empty = auto-detect the server's default libraryCALIBRE_MCP_ENABLE_WRITESet to 1 to enable the write tools (update/bulk-update/add/remove); off by defaultCALIBRE_MCP_CALIBREDB_PATHPath to the calibredb binary; empty = auto-discover the standard install locationローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
14掲載時のツール一覧 · 1 日前に更新
このツールにパラメーターはありません。
詳細
📚 calibre-mcp
現存する最も高機能なCalibre MCP サーバー — Claude(または任意のMCP クライアント)を お使いのCalibre電子書籍ライブラリに接続し、キーワードだけでなく、 意味で検索できます。
AI アシスタントに*「私の本の中で、コンシューマーグループのリバランスについて解説しているのはどれ?」*と尋ねると、 800冊以上の本全体、または1冊の本の中から、該当する章を正確に見つけられます。メタデータの整理、重複の解消、 ライブラリの安全な編集も、すべて自然言語で行えます。
1つの質問 → セマンティック検索 → 3D表紙フロー → 書籍カード → 該当箇所 → 図ビューアー。すべてClaude Desktop(MCP Apps)内で完結します
✨ 主な特長
- 19個のツールで幅広い機能をカバー:検索、コンテンツの閲覧、カテゴリの参照、整理、 および(オプトインで)書き込み — メタデータの更新、一括編集、重複の統合、インポート、削除、 バンドル(名前付きのトピック別フィルター)の管理。
- セマンティック検索 — ライブラリ全体または1冊の本の中を対象に、意味ベースのベクトル検索と キーワード検索を組み合わせて検索します。多言語に対応(英語とロシア語で検証済み、 言語をまたいだクエリも機能します)。この機能を備えたCalibre MCP サーバーはほかにありません。
- チャット内UI(MCP Apps) — MCP Appsに対応したホスト(Claude Desktop)では、ライブラリ検索の結果を
インタラクティブな表紙カルーセルとして表示します。
calibre_get_bookは、表紙、評価、 既読・類似検索アクションを備えた書籍詳細カードを表示し、calibre_get_figuresは、アシスタントが取得したものと 同じ図表を表示する図ビューアーを表示します。テキストのみのホストには影響しません。 - 整理ツール — 統合の安全性スコア付きで重複を検出し、メタデータの品質を監査し、
生のファイル名(
795731065.pdf→ Fundamentals of Software Engineering)が付いた本の正しいメタデータをOpen Library / Google Booksから取得します。 - デフォルトで安全 — 書き込みを明示的に有効にしない限り読み取り専用です。破壊的な操作はまずプレビューを表示し、 確認を求めます。すべての書き込みはContent Server経由で行うため、Calibre GUIとの競合を防げます。
📋 必要条件
- Calibreと、実行中のContent Server(Calibreで「接続/共有 → Content serverを起動」)。Calibre 9.xでテスト済みです。 最近のバージョンであれば動作するはずです。
- npm/npxでインストールする場合はNode.js ≥ 22.16が必要です(Claude Desktopのワンクリックバンドルでは不要です。 Desktopには独自のランタイムが同梱されています)。
- PDFのテキスト抽出を最適化する場合は、popplerの
pdftotext(brew install poppler)またはPyMuPDFを備えたPython 3(pip install pymupdf)が任意で必要です。 これらがない場合、サーバーはCalibreのebook-convertにフォールバックします。
🚀 クイックスタート
最も簡単 — エージェントにインストールを任せる
ガイド付きインストーラーのスキルを取得して、作業をすべてエージェントに任せましょう。
npx skills@latest add caelum29/calibre-mcp # pick calibre-mcp-setup
次に、エージェントに 「calibre-mcp をセットアップして」 と伝えます。calibre-mcp-setup スキルが、以下のすべてを進めます。事前確認(Node、calibredb、Content Server)、Calibre 側の設定、クライアントに応じたインストール(macOS/Windows/Linux)、そして calibre_ping による検証を行い、あなた自身が回答する必要のある質問(使用するクライアント、書き込みのオン/オフ)だけを尋ねます。Agent Skills 対応のあらゆる実行環境(Claude Code、Copilot、Amp、…)で動作します。手動で設定したい場合は、以下からクライアントを選んでください。
Claude Code
MCP サーバーのみ:
claude mcp add calibre -- npx -y calibre-mcp
または、プラグインをインストールすると、設定ダイアログ(サーバー URL、ライブラリ、書き込みの許可)からインストール時に設定でき、MCP サーバーと関連スキルをまとめて導入できます。
/plugin marketplace add caelum29/calibre-mcp
/plugin install calibre-mcp@caelum29
Claude Desktop(ワンクリック)
最新リリースから .mcpb バンドルをダウンロードして開くと、Claude Desktop がインストールし、設定(サーバー URL、ライブラリ、書き込みのオン/オフ)を尋ねます。ターミナルは不要です。
インストール時の警告について。 Claude Desktop は、組み込みディレクトリではなくファイルからインストールするすべての拡張機能に対して、「インストールすると、この拡張機能にコンピューター上のすべての項目へのアクセスが許可されます…開発者情報は Anthropic によって確認されていません」 と表示します。この拡張機能に固有の警告ではありません。サーバーは、以下の
npxインストールと同様に、ユーザーアカウントでローカルの Node プロセスとして実行されます。バンドルはこのリポジトリから CI によってビルド、公開されているため、実行する内容を監査できます。続行するには Install をクリックしてください。
バンドルを小さく保つため、オプションの埋め込み依存関係は含まれていません。そのため、2 つのセマンティック検索ツールは利用できない状態になります。メタデータ検索と全文検索は問題なく動作します。セマンティック検索を使う場合は、代わりに以下の npx インストールを使用してください。
Claude Desktop(JSON 設定)
claude_desktop_config.json に追加します。
{
"mcpServers": {
"calibre": {
"command": "npx",
"args": ["-y", "calibre-mcp"]
}
}
}
Cowork
Claude Desktop でサーバーを設定してください(上記のどちらの方法でも構いません)。Desktop がローカル MCP サーバーを Cowork に自動的に橋渡しします。追加の設定は不要です。
スキルのみ — あらゆるエージェント(Claude Code、Codex、Cursor、…)
このリポジトリの Agent Skills — ガイド付きインストーラー(calibre-mcp-setup)、calibre-mcp の使用ガイド、2 つの distill スキル — は、skills.sh インストーラーを使って、Agent Skills 対応のあらゆる実行環境にインストールできます。
npx skills@latest add caelum29/calibre-mcp
スキルと対象のエージェントを対話形式で選択できます。mattpocock/skills と同様に、2 つの方式があります。skills.sh はファイルをセットアップ先にコピーするため、自由に編集できます。一方、Claude Code プラグイン(上記)は、管理され、自動更新されるバンドルとしてスキルを保持します。どちらの方法でも、スキルはこの MCP サーバーのツールを使用するため、サーバーもインストールしてください。または、calibre-mcp-setup スキルに任せることもできます。スキルがあらゆるエージェントに対して、事前確認、クライアントごとのインストール(macOS/Windows/Linux)、検証を案内します。
初めて使うとき — 5つのプロンプトで試す
サーバーはデフォルトのライブラリを自動検出します。Content Server に接続できない場合は、実行可能なヒントを stderr に記録します。それから、次の順に試してください。
- 「自分の calibre ライブラリを一覧表示して」 — 接続の確認です。
- 「Rust に関する本を探して」 — メタデータ検索です。Claude Desktop では、結果が上部の表紙カルーセルとして表示されます。
- 「The Rust Programming Language を表示して」 — メタデータ全体が表示されます。表紙、評価、フォーマットごとの読書ボタンを含む書籍カードとして表示されます。
- 「JWT Handbook の図 2.3 を表示して」 — 図が画像としてアシスタントに渡され、Claude Desktop では拡大・縮小や移動ができる図ビューアにも表示されます。最初の説明が実際に見えるものと違う場合は、*「画像を見て、実際には何が描かれている?」*と尋ねてください。モデルは画像のピクセルを読む前に、記憶をもとに図について回答することがあります(ツールの結果によって画像を見るよう促されます。「トラブルシューティング」を参照してください)。
- 「Kafka の本のセマンティックインデックスを構築して」 — 意味ベースの検索を行うための初回準備です(以下を参照)。
- 「自分の本のうち、コンシューマーグループのリバランスについて説明しているのはどれ?」 — セマンティック検索です。順位付けされた書籍、または特定の本に絞り込んだ場合は該当箇所を正確に回答します。
おまけ:*「ライブラリの問題点は?」*で品質監査を実行します(メタデータの欠落、ファイル名そのままのタイトル、無効な ISBN など)。
✍️ 書き込みを有効にする
書き込みツール(calibre_update_book、calibre_bulk_update、calibre_add_book、calibre_remove_book、calibre_merge_books、calibre_manage_bundles)は、デフォルトで非表示です。読み取り専用の list アクションも含め、calibre_manage_bundles は非表示になります。これは、制御がアクション単位ではなくツール単位で行われるためです。有効にするには、独立した2つのスイッチをオンにする必要があります。
-
MCP 側の制御 —
CALIBRE_MCP_ENABLE_WRITE=1を設定するか、Desktop バンドルの設定で Enable writes にチェックを入れます。これを設定しないと、書き込みツールは登録されません。 -
Calibre 側の制御 — Content Server でローカル書き込みを許可する必要があります。Calibre GUI に組み込まれたサーバーは、デフォルトで読み取り専用です。そのため、以下の GUI オプションを有効にするか、
--enable-local-writeを指定してスタンドアロンサーバーを実行してください。# quit the Calibre GUI first (it holds the library lock), then: calibre-server --enable-local-write --port 8080 "/path/to/Calibre Library"アプリを終了せずに、GUI 組み込みサーバーで有効にすることもできます。Calibre → 環境設定 → ネット経由で共有 → 詳細を開き、「認証されていないローカル接続によるライブラリの変更を許可する」(つまり、ローカルからの書き込みアクセスを許可する)にチェックを入れてから、GUI で Content Server を再起動してください。これは、組み込みサーバーで
--enable-local-writeを指定するのと同等です。
最初のスイッチだけをオンにすると、書き込みツールは表示されますが、Calibre が書き込みを拒否します。そのことはエラーメッセージに明記されます。GUI 組み込みサーバーに対する読み取りは問題なく動作します。
安全対策:calibre_bulk_update では書籍を明示的に選択する必要があります(ids または query を指定します。「すべての本」がデフォルトになることはありません)。また、preview: false を指定するまでは変更内容をプレビューします。calibre_remove_book は confirm: true を指定するまでドライランで動作します。削除するとレコードとファイルが完全に削除されます。calibre_merge_books は confirm: true を指定するまでマージの全計画を表示し、ゴミ箱に移動されたソースは Calibre のゴミ箱から復元できます(safe モードではソースを完全に保持します)。calibre_add_book では、許可リストに登録されたフォルダー(CALIBRE_MCP_ADD_ROOTS)のファイルのみをインポートできます。
🔎 セマンティック検索
詳細はこちらをご覧ください:
docs/SEMANTIC-SEARCH.md— インデックス作成、ハイブリッド検索、再ランキングの仕組みを説明しています。
意味に基づく検索はオプトインで、次の2つが必要です。
- 埋め込みの依存関係 —
@huggingface/transformersはoptionalDependenciesに含まれているため、通常のnpx calibre-mcp/npm installで 自動的にインストールされます。(MCPB バンドルでは除外されます。) - インデックス — Claude に
calibre_build_indexを実行するよう依頼し、対象の書籍を指定します (ID または Calibre クエリで指定)。最初のビルドでは、埋め込みモデル (multilingual-e5-small、約118 MB、初回のみ)がインデックスディレクトリにダウンロードされます。それ以降は すべてオフラインで動作します。インデックス作成は Apple Silicon で毎秒約100チャンクの速度です。
重要
検索結果は、別途約576 MBのモデルを初回のみダウンロードするクロスエンコーダーの再ランキングで精度が向上します。
calibre_build_indexの実行中(時間がかかると想定されるステップ)に、モデルが事前にダウンロードされます。キャッシュ済みモデルのないマシンで検索を先に実行すると、ハイブリッド検索またはベクトル検索の初回実行時に、代わりにモデルがダウンロードされます。再ランキングでは、セマンティック検索ごとに CPU 処理が数秒追加されます。無効にするにはCALIBRE_MCP_RERANK=offを設定します(高速になりますが、ランキング精度は目に見えて低下します)。
その後、calibre_semantic_search で*「私の蔵書の中で、コンシューマーグループのリバランシングについて説明している本は?」*といったクエリに回答できます。ライブラリ全体(scope: library、書籍をランキング)または1冊の書籍内(scope: book、該当箇所を返す)を検索できます。検索方式はデフォルトでハイブリッドです。ベクトルコサイン類似度と語幹処理済みキーワード FTS を相互順位融合で統合し、モデルが利用可能な場合はクロスエンコーダーで再ランキングします(候補上位30件)。ある言語のクエリで、別の言語の該当箇所も見つかります(EN⇄RU で検証済み)。
埋め込みがなくても、キーワード検索は機能します。 mode: keyword はクエリ時にモデルを使用しませんが、インデックスは必要です。埋め込みモデルがインストールされていない場合(デフォルトの MCPB バンドルには含まれていません)は、keywordOnly: true を指定して calibre_build_index を実行し、キーワード専用のインデックスを作成してください。モデルが存在しない場合は自動的に作成されます。その後、mode: keyword で検索します。この方法では ML への依存関係は一切ありません。mode: vector は対処方法を示すエラーになり、mode: hybrid はキーワード検索にフォールバックします(注記が表示されます)。モデルをインストールした状態で再ビルドすると(force: true)、セマンティックランキングが追加されます。
🧰 ツール
パラメーターと使用例を含む完全なリファレンス:
docs/TOOLS.md。
| ツール | アクセス | 機能 |
|---|---|---|
calibre_search | 読み取り | タイトル/著者/ISBN/タグまたはCalibreのクエリ構文(mode: meta)で書籍を検索するか、全文検索(mode: fts)を行います。scope: bookでは1冊の書籍内を検索し、filterではバンドルに範囲を限定します |
calibre_get_book | 読み取り | 1冊の書籍(idまたはuuid)の完全なメタデータ、形式、表紙リンクを取得します。include_cover: trueにすると、結果に表紙画像が埋め込まれます |
calibre_get_content | 読み取り | 書籍のテキストを上限付きの抜粋として読み取ります。カーソルを使って書籍全体を読み進められます。structure: trueにすると、章のマップ(見出し、オフセット、章ごとのカーソル)が返されます — EN + RU/UK |
calibre_get_figures* | 読み取り | キャプションとページ位置を含む、書籍の図やイラストの一覧を取得します。取得した図はチャット内の図ビューアーに表示されます |
calibre_list_categories | 読み取り | タグ、著者、シリーズ、出版社、カスタム列を件数とともに表示します |
calibre_list_libraries | 読み取り | Content Serverが公開しているライブラリの一覧を取得します(デフォルトのライブラリも表示) |
calibre_semantic_search | 読み取り | 意味ベースの検索を行います。mode: hybrid|vector|keywordを指定でき、ライブラリまたは書籍の範囲に限定できます。filterではバンドルに範囲を限定します |
calibre_build_index | 読み取り* | 選択した書籍のローカルなセマンティックインデックスを構築/更新します(ローカルのインデックスファイルのみを書き込みます)。keywordOnly: trueにすると、モデル不要のキーワードインデックスを構築します |
calibre_find_duplicates | 読み取り | 重複グループとマージの安全性スコアを返します。mode: compareでは2冊の書籍の差分を表示します |
calibre_quality_report | 読み取り | 監査:メタデータの欠落、ファイル名そのままのタイトル、無効なISBN、著者名の並べ替えに関する問題、シリーズの欠落を検出します |
calibre_recover_metadata | 読み取り | Open Library → Google Booksから実際のメタデータを提案します。プレビューのみで、適用にはcalibre_update_bookを使用します |
calibre_extract_isbn | 書き込み | 書籍本文をスキャンして有効なISBNを探し、isbn識別子に設定します。まずプレビューし、apply: trueで適用します |
calibre_update_book | 書き込み | 1冊の書籍のメタデータフィールド(#custom列を含む)を設定し、適用された差分を返します |
calibre_bulk_update | 書き込み | 複数の書籍に同じ変更を適用します。対象の選択が必要で、まずプレビューします |
calibre_add_book | 書き込み | ローカルの電子書籍ファイル(パスは許可リストで制限)をインポートします |
calibre_remove_book | 書き込み、破壊的 | 書籍(レコードとファイル)を完全に削除します。確認がなければドライランです |
calibre_merge_books | 書き込み、破壊的 | 重複レコードをマージします。形式を対象の書籍に移動し、Calibreのルールに従ってメタデータを統合して、元のレコードをゴミ箱に移動します。確認がなければ計画のドライランを行います |
calibre_manage_bundles | 書き込み | バンドルの一覧表示/作成/更新/削除を行います。バンドルはCalibreの保存済み検索を基盤とする、名前付きのトピック別フィルターです。名前が-で始まるバンドルは、その書籍を検索結果に自動表示しません。まずプレビューします |
calibre_ping | 読み取り | ヘルスチェック:Calibreにエンドツーエンドで接続できますか? |
* 図は実際の画像としてアシスタントに渡されますが、モデルは図を確認する前に記憶をもとに説明してしまうことがあります。最初の説明が画像と一致しない場合は、*「画像を見てください。実際には何が描かれていますか?」*と再度尋ねてください(詳しくはトラブルシューティングを参照)。
MCP Appsホストでは、calibre_searchとcalibre_semantic_search(ライブラリ範囲)の結果は表紙カルーセルとして、calibre_get_bookは書籍カードとして、calibre_get_figuresは図ビューアー(閲覧ペイン+マージンレール、クリックすると100%にズーム)として表示されます。これにより、アシスタントが読んでいる図を確認できます。表紙はローカルのContent Serverから読み込まれます。それ以外の環境では、同じツールから通常のテキスト結果が返されます。どちらの場合も設定は不要です。
📚 コンパニオンスキル:calibre-distill
上記のツール(章の構成マップ(calibre_get_content structure=true)に加え、書籍内のキーワード検索とセマンティック検索)を使って、ライブラリ内の書籍を再利用可能な構造化スキル(フレームワーク、メンタルモデル、用語集、チートシート)にまとめるエージェントスキルです。英語とロシア語/ウクライナ語の書籍に対応し、一時ファイルは使用せず、ゲート付き書き込みツールを通じて、学んだ内容をカタログに(タグとまとめノートとして)記録することもできます。
このリポジトリの skills/calibre-distill/ に含まれています。npx skills@latest add caelum29/calibre-mcp または Claude Code プラグイン(クイックスタートを参照)からインストールするか、シンボリックリンクを作成して手動でインストールしてください。
ln -s "$PWD/skills/calibre-distill" ~/.claude/skills/calibre-distill
次のように依頼します。「書籍 187 を kafka-ops というスキルにまとめてください」。注:MCPB バンドルにはスキルを同梱できません。Claude Desktop では、MCP サーバーとは別にスキルをインストールしてください。
コンパニオンスキル:calibre-distill-topic
複数の書籍(3 冊以上)にまたがる1 つのトピックを、単一の概念別スキルにまとめる兄弟スキルです。意思決定フレームワーク、概念ごとのセクション、情報源を横断する設定表、明示的な*「情報源同士がどこで食い違うか、あるいは補完し合うか」*のセクション、さらに実際の情報源との紐付けを兼ねた ISBN 書誌を作成します。1 冊の書籍ではなく、書棚にある複数の書籍をもとにトピック学習用資料を作りたい場合に使用してください(1 冊の書籍のまとめには calibre-distill を使用します)。skills/calibre-distill-topic/ に含まれており、上記と同じ skills.sh/プラグイン/シンボリックリンクの方法でインストールできます。
次のように依頼します。「書籍 187 182 571 186 から kafka の信頼性をまとめて、スキルにしてください」。
生成されたスキルは、同梱の検証ツールでチェックできます。検証内容は、原文との逐語的一致(原書と照合する 8-gram シャード)、引用の上限、圧縮率の下限、見出しの対応、カーソルの漏出、出典表示です。
pnpm build && node scripts/legal-gate.mjs <skill-dir> --book <id> [--book <id>…]
⚙️ 設定
すべて任意です。Content Server がデフォルトのポートで起動していれば、設定なしで動作します。環境変数(デスクトップバンドルでは同じ設定を UI フィールドとして表示します):
| 変数 | デフォルト | 用途 |
|---|---|---|
CALIBRE_MCP_SERVER_URL | http://localhost:8080 | Calibre Content Server のベース URL |
CALIBRE_MCP_LIBRARY | 自動検出 | ライブラリ名。空の場合はサーバーのデフォルトライブラリを使用します |
CALIBRE_MCP_ENABLE_WRITE | オフ | 書き込みのマスターゲート(1/true/yes) |
CALIBRE_MCP_CALIBREDB_PATH | 自動検出 | calibredb バイナリ。標準のインストールパスを確認し、次に PATH から探します |
CALIBRE_MCP_INDEX_DIR | プラットフォームのデータディレクトリ¹ | セマンティックインデックスと埋め込みモデルのキャッシュ |
CALIBRE_MCP_SEMANTIC_FLOOR | 0.78 | セマンティック検索の結果が低信頼度としてフラグ付けされる、コサインスコアのしきい値 |
CALIBRE_MCP_RERANK | オン | セマンティック検索でのクロスエンコーダーによる再ランキング処理(約 576 MB のモデルを使用し、クエリごとに数秒の CPU 時間が必要)。無効にするには off/false/0 を設定します |
CALIBRE_MCP_MAX_BOOK_BYTES | 268435456(256 MB) | calibre_build_index/calibre_get_content が展開する書籍ダウンロードの最大サイズ。これを超える書籍はスキップされます² |
CALIBRE_MCP_INDEX_BUSY_TIMEOUT_MS | 5000 | 別のサーバープロセス(例:Claude Desktop と Claude Code の同時使用)がインデックスを保持している場合、インデックスへの書き込みが失敗するまで待機する時間 |
CALIBRE_MCP_ADD_ROOTS | ~/Documents、~/Downloads | calibre_add_book がインポートできるフォルダー(パス区切り文字で区切ります) |
CALIBRE_MCP_BOARD_STYLE | shelf | MCP Apps ホストでの検索結果ウィジェットのスタイル:shelf(スクロール可能な表紙の棚)または coverflow(3D 表紙フロー。デスクトップバンドルでは Coverflow search results の切り替えとして表示します) |
¹ macOS は ~/Library/Application Support/calibre-mcp/index、Windows は
%APPDATA%\calibre-mcp\index、Linux は $XDG_DATA_HOME/calibre-mcp/index です。
² 上限サイズは、ディスク上のファイルではなく、Content Server が提供するデータを基準に設定してください。サーバーからは、はるかに大きなコピーが返される場合があります(8 MB の PDF が 70 MB として提供されるなど)。そのため、ディスク上のサイズを基準に上限を設定すると、書籍が気付かれないままスキップされます。
🩺 トラブルシューティング
症状と対処方法の詳細:
docs/TROUBLESHOOTING.md。
- 「Calibre に接続できません」/接続が拒否される — Content Server が起動していません。
Calibre で 接続/共有 → Content Server を起動 を選択するか、
CALIBRE_MCP_SERVER_URLを正しいホスト/ポートに設定してください。 - 書き込みが拒否される/「Forbidden」 — Content Server でローカルへの書き込みが許可されていません。
上記の 書き込みを有効にする を参照してください。
--enable-local-writeを指定して スタンドアロンサーバーを実行するか、GUI の ネットワーク経由の共有 → 詳細 オプションにチェックを入れ、 Content Server を再起動してください。 - 全文検索で結果が返らない/エラーが発生する — ライブラリで Calibre の FTS インデックスが有効になっていません。 Calibre で 環境設定 → 検索 → 全文検索 を開いて有効にし、インデックス作成が完了するまで待ってください (大規模なライブラリでは時間がかかる場合があります)。
- 「embedding model unavailable」 — オプションの
@huggingface/transformersパッケージが インストールされていません(MCPB バンドルでは想定される状態です)。npx によるインストールを使用するか、 サーバーと同じディレクトリでnpm install @huggingface/transformersを実行してください。これを使わずに検索するには、 キーワードのみのインデックスを作成し(calibre_build_index keywordOnly=true)、mode: keywordを使用してください。 calibredbが見つからない — Calibre をインストールするか、CALIBRE_MCP_CALIBREDB_PATHを バイナリのパスに設定してください(macOS:/Applications/calibre.app/Contents/MacOS/calibredb)。- PDF から空のテキストが抽出される — スキャン画像の PDF です。Calibre にも、こちらにも OCR 機能はありません。
- ライブラリが見つからない(404) —
calibre_list_librariesに表示されるライブラリの 表示名 または ID を渡してください。 不明な場合はライブラリを指定せず、サーバーにデフォルトを選択させてください。
🛠️ 開発
pnpm install
pnpm build # tsc → dist/
pnpm test # vitest (unit; no network, no model download)
pnpm test:model # gated embedding-model integration tests (~118 MB download)
pnpm inspect # MCP Inspector against the built server
pnpm pack:mcpb # build the Claude Desktop .mcpb bundle
このコードベースはクリーンアーキテクチャを採用しています。ツールハンドラー、Calibre クライアント、セマンティックコアは SDK に依存せず、src/server.ts のみが MCP SDK を使用します。ユーザー向けドキュメント(ツールリファレンスとセマンティック検索ガイド)は docs/ にあります。
質問、アイデア、セットアップの共有は ディスカッションへ。バグ報告や PR は Issuesへお寄せください。
📄 ライセンス
MIT © 2026 Artem Sorochynskyi
Calibre とは無関係の独立したプロジェクトです。
Calibre 自体は
Kovid Goyal のオープンソースプロジェクト(GPLv3)であり、
このサーバーは calibredb と Content Server を介して、別個のプログラムとして操作します。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。