calibre-mcp
calibre-mcp
ローカルな MCPサーバー (stdio) で、LLMホスト(Claude Desktop、Claude Code、または任意の MCP 互換クライアント)が Calibre の電子書籍ライブラリを会話的に管理できるようにします。検索、メタデータ編集、追加、 変換、重複排除、削除、メール送信を、すべて人間が介在する安全性を備えて行えます。
ほとんどのCalibre MCPサーバーは読み取り専用です。検索と一覧表示のみです。しかし、これは書き込みを行います。しかも安全に。 メタデータの編集、追加、変換、削除は、ツールが実際にライブラリを破損または失う可能性がある操作です。そのため、ここでのすべての変更は、偶発的にそれが起こらないように設計された仕組みを通ります。
破壊的な操作にはすべて「計画 → 確認」を実施。 最初の呼び出しで人間が読める差分と
confirmation_tokenが返され、その正確なトークンで再呼び出しするまで何も変更されません。すべての書き込み前に自動で
metadata.dbをバックアップ(ローテーション式、最新20件保持)。削除は復元可能 — ゴミ箱コピー および Calibreのリサイクルビンに送られ、完全削除はされません。
読み取りは何も破損させない — SQLite接続は
mode=roで開かれます。
CalibreのGUIをクリックして操作するのをやめ、代わりにチャットからライブラリを管理するために作られました。また、ユーザーのファイルを削除することが許可されているツールをどう設計するかのショーケースとして意図的に設計されています。ハイブリッドI/O設計、明示的な障害分類、すべての破壊的操作に対する人間の承認ゲート、そして実際のユーザーデータに一切触れないテストスイート。何をするか、なぜそうするかは PRODUCT.md を、設計の詳細は ARCHITECTURE.md を参照してください。
ハイブリッド設計の理由
読み取り(
search、list、view、重複検出)はmetadata.dbを直接、読み取り専用で照会します。高速で、構造的にライブラリを破損させることがありません(SQLite接続はmode=roで開かれます)。書き込み(
edit、add、remove、convert、email)は Calibre 自身のCLIツール(calibredb、ebook-convert、calibre-smtp)を経由します。生のSQLは使わないため、Calibre が自身のデータベースに対して権威を持ち続けます。すべての書き込みの前に 自動の
metadata.dbバックアップ(ローテーション式、最新20件保持)が実行されます。削除は復元可能:ファイルは管理されたゴミ箱フォルダにコピーされ、かつ ブックは Calibre のリサイクルビンに送られます。完全削除はされません。
変更または外部送信を行うすべてのツールは2段階(計画 → 確認)です。最初の呼び出しで人間が読めるレビューと
confirmation_tokenが返され、その正確なトークンで再呼び出しするまで何も変更されず、何も送信されません。
これらの選択の背後にある完全な根拠、モジュール境界、決定ログは ARCHITECTURE.md にあります。
Related MCP server: calibre-manager
要件
Calibre がインストールされ、
calibredbとebook-convertがPATHに含まれていること(calibredb --version)。email_bookを使う場合はcalibre-smtpも必要です。Python ≥ 3.12 と
uv。
インストール
ゼロクローン(推奨) — uv がリポジトリから直接ビルドして実行します。手動チェックアウトは不要です。
uvx --from git+https://github.com/gustavofsousa/calibre-mcp calibre-mcpローカルチェックアウトから(開発用、または特定の状態に固定する場合):
git clone https://github.com/gustavofsousa/calibre-mcp calibre-mcp
cd calibre-mcp
uv sync設定
サーバーは 1つの ライブラリを管理し、環境変数で設定します。
変数 | 必須 | デフォルト | 目的 |
| はい | — | Calibreライブラリディレクトリ( |
| いいえ |
| 書き込み前のバックアップとゴミ箱ファイルが保存される場所。 |
サーバーは起動時に CALIBRE_LIBRARY_PATH が未設定またはディレクトリに metadata.db がない場合、明確なエラーで即座に失敗します。
email_book にはさらにSMTPリレーの資格情報が必要です(遅延読み込みされます。サーバーはそれらなしでも正常に起動し、email_book だけが不足している場合に失敗します)。
変数 | 必須 | デフォルト | 目的 |
| メール用 | — | SMTPリレーホスト。 |
| メール用 | — | SMTPユーザー名。 |
| メール用 | — | SMTPパスワード。ログに記録されず、ツール出力にも一切返されません。 |
| メール用 | — | 送信元アドレス。 |
| いいえ |
| SMTPポート。 |
| いいえ |
|
|
Claude Desktop / Claude Code
MCP設定(例:claude_desktop_config.json)に追加します。ゼロクローン — uvx 経由でリポジトリから直接実行します。
{
"mcpServers": {
"calibre": {
"command": "uvx",
"args": ["--from", "git+https://github.com/gustavofsousa/calibre-mcp", "calibre-mcp"],
"env": {
"CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
}
}
}
}または、ローカルチェックアウトから:
{
"mcpServers": {
"calibre": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/calibre-mcp", "run", "calibre-mcp"],
"env": {
"CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
}
}
}
}手動実行
CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run calibre-mcp
# or equivalently:
CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run python -m calibre_mcpサーバーは stdio(JSON-RPC)で通信します。MCPフレーミング以外は stdout に何も出力しません。すべてのログは意図的に stderr に送られます(ARCHITECTURE.md を参照)。
ツール
ツール | 機能 | ゲート |
| Calibre検索クエリ( | 読み取り専用 |
| ページング・ソート可能な一覧表示。Calibre GUIが書き込みロックを保持していても動作します。 | 読み取り専用 |
| 1つのブックIDの完全なメタデータを取得します。 | 読み取り専用 |
| 正規化された(タイトル、著者)による重複の可能性があるブックのアドバイザリレポート。マージはしません。 | 読み取り専用 |
| ホワイトリスト化されたフィールドセット(タイトル、著者、タグ、シリーズ、評価、コメントなど)を編集します。 | 計画 → 確認 |
| 1つのバッチでN冊のブックにフィールド変更を適用します( | 計画 → 確認(バッチ) |
| ローカルファイルパスからブックを追加します。重複を正直に表示します。 | 単一ステップ(バックアップあり) |
| ディレクトリ内のすべての電子書籍ファイルを再帰的にインポートします。 | 追加のみ(バックアップあり) |
| 新しい形式( | 単一ステップ(バックアップあり) |
| 1回の呼び出しでN冊のブックを1つのターゲット形式に変換します。 | 追加のみ(バックアップあり) |
| 復元可能な削除:ゴミ箱コピー + Calibreリサイクルビン。完全削除はされません。 | 計画 → 確認 |
|
| 計画 → 確認 |
さらに、MCP リソース として calibre://library/stats があります。これはツール呼び出しなしで読み取れる集計ライブラリプロファイル(合計数、形式/言語の構成、メタデータの完全性、データ品質フラグ)です。
各ツールの完全な契約(エッジケース、エラー条件、正確なフィールドホワイトリスト)は server.py のdocstringに文書化されています。これらのdocstringはLLMホストが参照するものであり、APIリファレンスを兼ねています。
開発
uv run ruff check src tests # lint
uv run pytest # full suite (unit + integration + e2e)
uv run pytest -m unit # fast unit tests only3つの階層(unit、integration、e2e)にわたる137のテスト。書き込みテストは実際のライブラリに一切触れません — ARCHITECTURE.md を参照してください。
プロジェクト構成
src/calibre_mcp/
├── server.py # FastMCP tool surface — the only stdio/MCP-aware module
├── library.py # CalibreLibrary facade — orchestrates every tool's business logic
├── sqlite_reader.py # Read-only metadata.db access (the only sqlite3 call site)
├── calibredb_runner.py # calibredb subprocess wrapper (search/edit/add/remove/add_format)
├── ebook_convert_runner.py # ebook-convert subprocess wrapper
├── calibre_smtp_runner.py # calibre-smtp subprocess wrapper
├── backup.py # metadata.db snapshots + recoverable trash
├── confirmation.py # plan→confirm token derivation/verification
├── config.py # env-driven startup config, fail-fast validation
└── errors.py # the failure taxonomy every layer maps toロードマップ
出荷済み:完全な読み取り/キュレーション/配布ループ(検索、一覧、表示、編集、追加、削除、変換、重複排除、メール送信)。次に予定されているもの — ライブラリの自己認識、一括操作、カバー/メタデータの強化、デバイス同期 — は .specs/ROADMAP.md で追跡されています。順序付けの理由と明示的にスコープ外のものも含まれます。
貢献
開発ワークフロー、PRが維持すべき不変条件、このリポジトリの背後にある仕様駆動プロセスの仕組みについては CONTRIBUTING.md を参照してください。
ライセンス
MIT © Gustavo F Sousa.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Agentic AI book creator: plan, write, illustrate, narrate, and publish books from any MCP client.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Agentic search over your Dewey document collections from any MCP-compatible client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables searching, reading, and managing a Calibre ebook library through natural language, with features like metadata search, full-text search, content extraction, and library management.Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server to manage and organize a Calibre ebook library, enabling metadata editing, search, conversion, and more through AI assistants.175MIT
- AlicenseNot gradedqualityBmaintenanceEnables semantic search over local Calibre libraries via MCP, allowing AI assistants to query books, annotations, and export bibliographies while keeping data private.9MIT
- AlicenseAqualityBmaintenanceConnects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.19590 npm31MIT