Skip to main content
Glama
calibre-mcp

calibre-mcp

calibre-mcp

CI License: MIT Python 3.12+ 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_LIBRARY_PATH

はい

—

Calibreライブラリディレクトリ(metadata.db を含むフォルダ)へのパス。

CALIBRE_MCP_BACKUP_DIR

いいえ

<library>/.calibre-mcp-backups/

書き込み前のバックアップとゴミ箱ファイルが保存される場所。

サーバーは起動時に CALIBRE_LIBRARY_PATH が未設定またはディレクトリに metadata.db がない場合、明確なエラーで即座に失敗します。

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

変数

必須

デフォルト

目的

CALIBRE_MCP_SMTP_RELAY

メール用

—

SMTPリレーホスト。

CALIBRE_MCP_SMTP_USERNAME

メール用

—

SMTPユーザー名。

CALIBRE_MCP_SMTP_PASSWORD

メール用

—

SMTPパスワード。ログに記録されず、ツール出力にも一切返されません。

CALIBRE_MCP_SMTP_FROM

メール用

—

送信元アドレス。

CALIBRE_MCP_SMTP_PORT

いいえ

465 (SSL) / 25 (TLS/none)

SMTPポート。

CALIBRE_MCP_SMTP_ENCRYPTION

いいえ

TLS

SSL、TLS、NONE のいずれか。

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

ツール

ツール

機能

ゲート

search_books

Calibre検索クエリ(author:asimov、tag:scifi など)を完全なブックメタデータに解決します。

読み取り専用

list_books

ページング・ソート可能な一覧表示。Calibre GUIが書き込みロックを保持していても動作します。

読み取り専用

get_book

1つのブックIDの完全なメタデータを取得します。

読み取り専用

find_duplicates

正規化された(タイトル、著者)による重複の可能性があるブックのアドバイザリレポート。マージはしません。

読み取り専用

update_metadata

ホワイトリスト化されたフィールドセット(タイトル、著者、タグ、シリーズ、評価、コメントなど)を編集します。

計画 → 確認

update_metadata_bulk

1つのバッチでN冊のブックにフィールド変更を適用します(list_mode add/remove/replace)。

計画 → 確認(バッチ)

add_book

ローカルファイルパスからブックを追加します。重複を正直に表示します。

単一ステップ(バックアップあり)

import_folder

ディレクトリ内のすべての電子書籍ファイルを再帰的にインポートします。

追加のみ(バックアップあり)

convert_book

新しい形式(epub、azw3、mobi、pdf)に変換します。追加のみで、元のファイルは保持されます。

単一ステップ(バックアップあり)

convert_book_bulk

1回の呼び出しでN冊のブックを1つのターゲット形式に変換します。

追加のみ(バックアップあり)

remove_book

復元可能な削除:ゴミ箱コピー + Calibreリサイクルビン。完全削除はされません。

計画 → 確認

email_book

calibre-smtp 経由でブックのファイルをメール送信します。最適な形式を自動選択します。

計画 → 確認

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server to manage and organize a Calibre ebook library, enabling metadata editing, search, conversion, and more through AI assistants.
      17
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables semantic search over local Calibre libraries via MCP, allowing AI assistants to query books, annotations, and export bibliographies while keeping data private.
      9
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.
      19
      590 npm
      31
      MIT