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-mcp

要件

• 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_LIBRARY_PATH が未設定またはディレクトリに metadata.db がない場合、明確なエラーで即座に失敗します。

email_book にはさらにSMTPリレーの資格情報が必要です（遅延読み込みされます。サーバーはそれらなしでも正常に起動し、email_book だけが不足している場合に失敗します）。

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 を参照）。

ツール

さらに、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 only

3つの階層（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.