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 的回收站——绝不永久删除。

• 每个变更或对外工具都是两步式（计划→确认）：第一次调用返回人类可读的审查以及 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

配置

服务器管理一个书库，通过环境变量设置：

如果 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

137 个测试分布在三个层级（unit、integration、e2e）；写入测试从不接触真实书库——参见 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 中，包括排序的理由和明确不在范围内的内容。

贡献

参见 CONTRIBUTING.md 了解开发工作流、PR 必须保持的不变量，以及这个仓库背后的规范驱动流程如何运作。

许可证

MIT © Gustavo F Sousa.