calibre-mcp

一个 MCP 服务器,让 AI 助手 (Claude Code、Claude Desktop、Cursor 等)能够读写你本地的 Calibre 电子书库。

在聊天中即可搜索书库、浏览最近添加的书籍、自动查重导入新电子书,以及管理"收件箱"文件夹。

• 常规设置下零配置:calibredb 可执行文件和 Calibre 图形界面正在使用的书库会在 macOS、Windows 和 Linux 上自动发现。

• 与语言环境无关:所有读取都通过 calibredb --for-machine(JSON)进行,因此结果永远不会取决于你的 Calibre 界面语言。

• 默认安全:查重依赖 Calibre 本身——书库中已存在相同"书名+作者"的书籍会被跳过,绝不会重复导入。

工具

Related MCP server: Calibre MCP Server

系统要求

• Calibre(任何附带 calibredb 的版本;已在 9.x 上测试)

• Python ≥ 3.10

安装

pipx(推荐)

pipx install calibre-mcp

uv

uv tool install calibre-mcp

pip

pip install calibre-mcp

从源码安装

git clone https://github.com/ZehuiTIAN/calibre-mcp.git
cd calibre-mcp
pip install -e ".[dev]"     # dev extras add pytest + ruff

配置

常规设置下一切都是可选的;每个值都可以通过环境变量固定。

注册到 Claude Code

claude mcp add calibre-mcp -- calibre-mcp

或添加到 ~/.claude.json → mcpServers(用户范围):

"calibre_mcp": {
  "type": "stdio",
  "command": "calibre-mcp",
  "args": [],
  "env": {
    "CALIBRE_LIBRARY_PATH": "/path/to/your/library",
    "CALIBRE_INBOX_DIR": "/path/to/your/inbox"
  }
}

注册到 Claude Desktop / Cursor

将相同的 JSON 块添加到 claude_desktop_config.json(Claude Desktop)或 Cursor 的 MCP 设置中的 MCP 服务器部分。

收件箱工作流

收件文件夹为手动下载的书籍提供了一个便捷的"查找 → 放入 → 归档"循环:

1. 将 CALIBRE_INBOX_DIR 指向一个文件夹,例如 ~/Downloads/Calibre-Inbox。

2. 将电子书下载到该文件夹。

3. 让助手运行 import_inbox。

每个文件都会添加到书库;成功添加的文件和重复文件归档到 imported/YYYY-MM/,失败的文件归档到 failed/——收件箱本身保持整洁,任何文件都不会被覆盖(名称冲突会添加 -1、-2 等后缀)。

支持的扩展名:.epub .pdf .mobi .azw .azw3 .djvu .cbz .cbr .fb2 .txt .md .docx .rtf .lit .prc .pdb .chm .htmlz。

注意事项

• 数据库锁:当 Calibre 图形界面打开着书库时,写入操作(add_books、import_inbox)可能因数据库锁错误而失败。只读工具仍可正常工作。导入前请关闭 Calibre(或切换到另一个书库)。

• 大型书库:add_books/import_inbox 会在每次添加前后对全部书籍 ID 做快照,实际运行很快,但每次导入的复杂度为 O(书籍数量)。

• 此工具只整理你的书库。它不包含搜索或下载功能;请仅用于你有权持有的内容。

开发

pip install -e ".[dev]"
ruff check .
pytest -m "not integration"      # unit tests, run anywhere
pytest                           # + integration tests (need local calibre)

集成测试会在 /tmp 下创建临时书库,绝不会触碰你的真实书库。

许可证

MIT — 参见 LICENSE。

中文速览

把本地 Calibre 书库接给 Claude/Cursor 等 AI 助手的 MCP 服务器:五个工具 (library_info / search_books / list_books / add_books / import_inbox), 自动发现 calibredb 和书库位置,全平台(Windows/macOS/Linux)开箱即用。

pipx install calibre-mcp
claude mcp add calibre-mcp -- calibre-mcp

导入时自动查重(书名+作者相同的书不会被重复导入);配合 CALIBRE_INBOX_DIR 收件箱目录,把下载的书丢进去、说一句"导入收件箱"即可 归档,处理完的文件自动归类到 imported/ 或 failed/。

注意:Calibre 桌面程序打开着同一书库时,写入操作可能因数据库锁失败, 导入前先关闭 Calibre。