calibre-mcp

# 📚 calibre-mcp [](https://www.npmjs.com/package/calibre-mcp) [](https://www.npmjs.com/package/calibre-mcp) [](https://registry.modelcontextprotocol.io) [](https://github.com/caelum29/calibre-mcp/actions/workflows/ci.yml) [](https://nodejs.org) [](./LICENSE) [](https://skills.sh/caelum29/calibre-mcp) > **现存最强大的 Calibre MCP 服务器** — 将 Claude（或任何 MCP 客户端）连接到您的 [Calibre](https://calibre-ebook.com) 电子书库，并按*含义*而非关键词搜索。 询问您的 AI 助手 *“哪些书籍解释了消费者组重新平衡？”* 并获取确切的章节 — 跨越 800 多本书籍或在单本书内。策划元数据、去重和安全编辑您的图书馆，所有操作都通过自然语言完成。 <p align="center"> <img src="https://raw.githubusercontent.com/caelum29/calibre-mcp/main/demo.gif" width="720" alt="Claude Desktop 搜索 Calibre 库并将结果渲染为交互式封面轮播" /> <br/> <em>Claude Desktop 将库搜索结果渲染为交互式封面板（MCP 应用）</em> </p> ## ✨ 亮点 - **17 种工具**，涵盖全部功能：搜索、读取内容、浏览类别、策划和（可选）写入 — 更新元数据、批量编辑、合并重复项、导入、删除。 - **语义搜索** — 基于含义的混合向量 + 关键词检索，适用于整个库 *或单本书*。多语言（英语 + 俄语验证，跨语言查询有效）。其他 Calibre MCP 服务器均无此功能。 - **聊天界面（MCP 应用）** — 在支持 MCP 应用的主机（Claude Desktop）中，库搜索结果会渲染为交互式封面轮播，`calibre_get_book` 会渲染为带有封面、评分和读取/相似操作的书籍详情卡。纯文本主机不受影响。 - **策划工具** — 查找具有合并安全评分的重复项，审计元数据质量，并通过 Open Library / Google Books 恢复具有原始文件名 (`795731065.pdf` → *软件工程基础*) 的书籍的真实元数据。 - **默认安全** — 除非您明确启用写入，否则只读；破坏性操作先预览，然后需要确认；所有写入都通过内容服务器路由，因此它们不会与 Calibre GUI 冲突。 ## 📋 要求 - **Calibre**，且 **内容服务器已运行**（在 Calibre 中：*连接/共享 → 启动内容服务器*）。已针对 Calibre 9.x 进行测试；任何最近的版本都应该有效。 - **Node.js ≥ 22.5**，用于 npm/npx 安装（对于 Claude Desktop 的一键式捆绑包不需要 — Desktop 自带运行时）。 - 可选，但为了最佳 PDF 文本提取：poppler 的 `pdftotext` （`brew install poppler`）或带有 PyMuPDF 的 Python 3 （`pip install pymupdf`）。如果没有它们，服务器会回落到 Calibre 的 `ebook-convert`。 ## 🚀 快速开始 ### 最简单 — 让您的代理为您安装 获取引导安装程序技能，并将整个任务交给您的代理： ```sh npx skills@latest add caelum29/calibre-mcp # 选择 calibre-mcp-setup ``` 然后告诉您的代理：**"设置 calibre-mcp"**。`calibre-mcp-setup` 技能驱动以下所有操作 — 预检查（Node、calibredb、内容服务器）、Calibre 端配置、适用于您的客户端（macOS/Windows/Linux）的正确安装以及 `calibre_ping` 验证 — 只需您回答问题（哪个客户端、写入开启/关闭）。在任何 Agent-Skills 兼容的框架（Claude Code、Copilot、Amp、...）中均有效。更喜欢手动操作？请选择下面的客户端。 ### Claude 代码 仅限 MCP 服务器： ```sh claude mcp add calibre -- npx -y calibre-mcp ``` 或安装插件 — 服务器 **和** 配套技能，一步完成，安装时带有设置对话框（服务器 URL、库、写入门控）： ``` /plugin marketplace add caelum29/calibre-mcp /plugin install calibre-mcp@caelum29 ``` ### Claude Desktop（一键式） 从 [最新版本](https://github.com/caelum29/calibre-mcp/releases/latest) 下载 `.mcpb` 捆绑包并打开它 — Claude Desktop 会安装它并提示设置（服务器 URL、库、写入开启/关闭）。无需终端。 > **关于安装警告。** Claude Desktop 显示 *“安装将授予此扩展程序访问您计算机上所有内容的权限... 开发者信息未得到 Anthropic 验证”*，适用于从文件而非内置目录安装的**每个**扩展程序 — 它不限于此扩展程序。服务器在您的用户帐户下作为本地 Node 进程运行，与下面的 `npx` 安装完全相同；捆绑包由 CI 从此存储库生成和发布，因此您可以审计您正在运行的内容。点击 **安装** 以继续。 > 捆绑包不包含可选的嵌入依赖项，以保持小巧，因此两个语义搜索工具报告自己不可用。元数据和全文搜索功能齐全。要进行语义搜索，请改用下面的 npx 安装。 ### Claude Desktop（JSON 配置） 添加到 `claude_desktop_config.json`： ```json { "mcpServers": { "calibre": { "command": "npx", "args": ["-y", "calibre-mcp"] } } } ``` ### Cowork 在 Claude Desktop 中配置服务器（上述任意方法）— Desktop 会自动将本地 MCP 服务器桥接到 Cowork。无需额外设置。 ### 仅限技能 — 任意代理（Claude Code、Codex、Cursor、...） 存储库的代理技能 — 引导安装程序（`calibre-mcp-setup`）、calibre-mcp 使用指南和两个蒸馏技能 — 可通过 [skills.sh](https://skills.sh) 安装程序安装到任何 Agent-Skills 兼容的框架中： ```sh npx skills@latest add caelum29/calibre-mcp ``` 交互式选择技能和目标代理。两种理念，与 [mattpocock/skills](https://github.com/mattpocock/skills) 相同：**skills.sh 复制** 文件到您的设置中，以便您可以修改它们；**Claude Code 插件** 将它们保留为托管的自动更新包。无论哪种方式，技能都驱动此 MCP 服务器的工具，因此也需要安装服务器 — 或让 `calibre-mcp-setup` 技能完成：它引导任何代理完成预检查、每个客户端的安装（macOS/Windows/Linux）和验证。 ### 首次联系 — 五项提示之旅 服务器自动检测您的默认库；如果内容服务器无法访问，它会记录一条可行的提示到标准错误流。然后尝试，按顺序： 1. *“列出我的 calibre 库”* — 连接性健康检查。 2. *“查找有关 Rust 的书籍”* — 元数据搜索；在 Claude Desktop 中，结果会渲染为上方的封面轮播。 3. *“显示我 Rust 编程语言”* — 完整的元数据；渲染为带有封面、评分和每种格式的读取按钮的书籍卡片。 4. *“为我的 Kafka 书籍构建语义索引”* — 针对含义搜索的预备步骤（参见下文）。 5. *“哪些书籍解释了消费者组重新平衡？”* — 语义搜索；回答带有排名的书籍，或在范围限定在一本书时返回确切的段落。 奖励：*“我的库有什么问题？”* 运行质量审计（缺少的元数据、原始文件名标题、无效的 ISBN）。 ## ✍️ 启用写入 **默认隐藏** 写入工具（`calibre_update_book`、`calibre_bulk_update`、`calibre_add_book`、`calibre_remove_book`、`calibre_merge_books`）。必须打开两个独立的开关： 1. **MCP 端门控** — 设置 `CALIBRE_MCP_ENABLE_WRITE=1` （或在 Desktop 捆绑包设置中勾选*启用写入*）。如果没有它，写入工具甚至不会被注册。 2. **Calibre 端门控** — 内容服务器必须允许本地写入。**默认情况下，Calibre GUI 内置的服务器是只读的**，因此要么启用 GUI 中的以下选项，要么运行带有 `--enable-local-write` 的独立服务器： ```sh # 先退出 Calibre GUI（它会占用库锁），然后： calibre-server --enable-local-write --port 8080 "/path/to/Calibre Library" ``` 或在**GUI 内置**服务器上启用它，无需退出应用程序：打开 Calibre → **首选项 → 网络共享 → 高级** 并勾选 **“允许未经身份验证的本地连接对库进行更改”** （即允许本地写入访问），然后从 GUI 重启内容服务器。 这是嵌入式服务器的 `--enable-local-write` 等价物。 仅开启第一个开关时，写入工具会出现，但 Calibre 拒绝写入 — 错误消息会明确告诉您这一点。读取操作对于 GUI 嵌入式服务器来说是正常的。 安全性行为：`calibre_bulk_update` 需要显式书籍选择（`ids` 或 `query` — 没有“所有书籍”的默认值）并在您传递 `preview: false` 之前预览更改。`calibre_remove_book` 在您传递 `confirm: true` 之前是只读的；删除会同时删除记录和文件，永久删除。`calibre_merge_books` 显示其完整的合并计划，直到您传递 `confirm: true`，而被删除的源文件可从 Calibre 的回收站恢复（模式 `safe` 保留它们）。`calibre_add_book` 仅从白名单文件夹导入文件（`CALIBRE_MCP_ADD_ROOTS`）。 ## 🔎 语义搜索 > 深入了解：[`docs/SEMANTIC-SEARCH.md`](./docs/SEMANTIC-SEARCH.md) — 索引、混合检索和重新排序的工作原理。 基于含义的搜索是**可选的**，需要两件事： 1. **嵌入依赖项** — `@huggingface/transformers` 是一个 `optionalDependencies` 条目，因此正常的 `npx calibre-mcp` / `npm install` 会自动获取它。 （仅限 MCPB 捆绑包排除它。） 2. **索引** — 要求 Claude 运行 `calibre_build_index` 以获取您关心的书籍 （按 ID 或 Calibre 查询）。第一次构建会下载嵌入模型 (`multilingual-e5-small`，约 118 MB，一次性）到索引目录；之后 所有操作都运行在本地。索引速度约为每 100 个块/秒在 Apple Silicon 上。 > [!IMPORTANT] > **搜索结果通过交叉编码器重新排序，其模型是一种单独的 > 约 576 MB 的一次性下载。** `calibre_build_index` 在构建过程中预下载它 — > 您已经预料到这一步会很慢。如果您直接跳到搜索，在没有缓存模型的机器上 > 会触发该下载。重新排序还会增加每个语义搜索的 CPU 时间；设置 > `CALIBRE_MCP_RERANK=off` 以禁用它（更快，但排名精度明显较低）。 然后 `calibre_semantic_search` 回答诸如 *“哪些书籍解释了消费者组重新平衡？”* 的查询 — 跨库（`scope: library`，对书籍进行排名）或在单本书内（`scope: book`，返回定位段落）。默认情况下，检索是**混合**的：向量余弦 + 带词干的关键词全文搜索，通过互惠排名融合，然后由交叉编码器（前 30 个候选者）重新排序，当其模型可用时。一种语言的查询可以找到另一种语言的段落（已验证的 EN⇄RU）。 **没有嵌入？关键词搜索仍然有效。** `mode: keyword` 在**查询时**不使用模型，但它需要索引。如果嵌入模型未安装（默认的 MCPB 捆绑包不包含它），请构建一个**仅限关键词**索引 — 使用 `calibre_build_index` 并设置 `keywordOnly: true`，或者在缺少模型时自动发生 — 并使用 `mode: keyword` 进行搜索。该路径没有 ML 依赖项。`mode: vector` 然后会报错并给出可行的提示，而 `mode: hybrid` 降级为关键词（带有注释）；请在安装模型后重新构建（`force: true`）以添加语义排名。 ## 🧰 工具 > 带有参数和示例的完整参考：[`docs/TOOLS.md`](./docs/TOOLS.md)。 | 工具 | 访问 | 它能做什么 | |---|---|---| | `calibre_search` | 读取 | 按标题/作者/ISBN/标签或 Calibre 查询语法 (`mode: meta`) 或全文 (`mode: fts`) 查找书籍；`scope: book` 在一本书中搜索 | | `calibre_get_book` | 读取 | 单本书（ID 或 UUID）的完整元数据、格式和封面链接；`include_cover: true` 将封面图像嵌入结果中 | | `calibre_get_content` | 读取 | 读取一本书的文本为有限摘录；通过光标遍历整个书籍。`structure: true` 返回章节地图（标题、偏移量、每章节的光标）— EN + RU/UK | | `calibre_list_categories` | 读取 | 浏览标签、作者、系列、出版商、自定义列及其计数 | | `calibre_list_libraries` | 读取 | 列出内容服务器公开的库（+ 哪个是默认库） | | `calibre_semantic_search` | 读取 | 基于含义的搜索；`mode: hybrid\|vector\|keyword`，库范围或书籍范围 | | `calibre_build_index` | 读取* | 为选定的书籍构建/刷新本地语义索引（仅写入本地索引文件）；`keywordOnly: true` 构建无模型的关键词索引 | | `calibre_find_duplicates` | 读取 | 具有合并安全评分的重复组；`mode: compare` 比较两本书 | | `calibre_quality_report` | 读取 | 审计：缺少的元数据、原始文件名标题、无效的 ISBN、作者排序问题、系列间隙 | | `calibre_recover_metadata` | 读取 | 通过 Open Library → Google Books 提出真实的元数据；**仅预览**，使用 `calibre_update_book` 应用 | | `calibre_extract_isbn` | **写入** | 从一本书的自身文本中扫描有效的 ISBN 并设置其 `isbn` 标识符；预览后，使用 `apply: true` 应用 | | `calibre_update_book` | **写入** | 设置一本书的元数据字段（包括 `#custom` 列）；返回应用的差异 | | `calibre_bulk_update` | **写入** | 对一组书籍应用相同的更改；需要选择，预览后 | | `calibre_add_book` | **写入** | 导入本地电子书文件（路径白名单） | | `calibre_remove_book` | **写入，破坏性** | 永久删除书籍（记录 + 文件）；除非确认，否则仅预览 | | `calibre_merge_books` | **写入，破坏性** | 合并重复记录：移动格式到目标，合并元数据按照 Calibre 的规则，删除来源；除非确认，否则仅预览计划 | | `calibre_ping` | 读取 | 健康检查：Calibre 是否可达？ | 在 MCP 应用主机中，`calibre_search` 和 `calibre_semantic_search`（库范围）会将结果渲染为封面板轮播，而 `calibre_get_book` 会渲染为书籍卡片 — 封面直接从您的本地内容服务器加载。其他地方的相同工具会返回其通常的文本结果；无需额外配置。 ## 📚 配套技能：calibre-distill 一种代理技能，它通过驱动上述工具，将您的图书馆中的一本书蒸馏成可重用的、结构化的技能（框架、思维模型、词汇表、备忘录）— 通过章节地图（`calibre_get_content structure=true`）加上书内关键词 + 语义搜索。适用于英文和俄/乌克兰书籍，无需临时文件，并可选地将您学到的内容通过门控写入工具标记回目录（标签 + 蒸馏笔记）。 它位于此存储库的 [`skills/calibre-distill/`](./skills/calibre-distill)。通过 `npx skills@latest add caelum29/calibre-mcp` 或 Claude Code 插件（参见 [快速开始](#-快速开始)）或手动通过符号链接安装： ```sh ln -s "$PWD/skills/calibre-distill" ~/.claude/skills/calibre-distill ``` 然后询问，例如 *“将书籍 187 蒸馏成名为 kafka-ops 的技能”*。注意：MCPB 捆绑包 无法运输技能 — 在 Claude Desktop 上单独安装技能。 ### 配套技能：calibre-distill-topic 一个姐妹技能，它将 **一个主题跨多本书籍**（≥3）合成成一个单一的 **基于关键字的技能** — 一个决策框架、每个概念的章节、跨源配置表、一个明确的 *“来源何处不同或互补”* 部分，以及 ISBN 参考书目，可实时绑定源。用于从书架上的书籍（≥3）创建主题学习辅助工具，而不是单本书蒸馏（单个书籍请求属于 `calibre-distill`）。位于 [`skills/calibre-distill-topic/`](./skills/calibre-distill-topic)；通过与上述相同的 skills.sh / 插件 / 符号链接路径安装。 然后询问，例如 *“将书籍 187、182、571、186 合成一个关于 Kafka 可靠性的技能。”* 生成的技能可以使用捆绑的验证器进行检查 — 重复率（8-gram 模数与源书籍的比较）、引用预算、压缩底线、标题镜像、光标泄漏和属性： ```sh pnpm build && node scripts/legal-gate.mjs <skill-dir> --book <id> [--book <id>…] ``` ## ⚙️ 配置 所有选项均为可选 - 默认端口上运行的内容服务器可以正常工作。 环境变量（桌面捆绑包公开了与UI字段相同的设置）： | 变量 | 默认值 | 用途 | |---|---|---| | `CALIBRE_MCP_SERVER_URL` | `http://localhost:8080` | Calibre 内容服务器基准 URL | | `CALIBRE_MCP_LIBRARY` | *自动检测* | 库名称；空值 = 服务器的默认库 | | `CALIBRE_MCP_ENABLE_WRITE` | 关闭 | 主写权限（`1`/`true`/`yes`） | | `CALIBRE_MCP_CALIBREDB_PATH` | *自动发现* | `calibredb` 二进制文件；通过标准安装路径，然后是 `PATH` 找到 | | `CALIBRE_MCP_INDEX_DIR` | 平台数据目录¹ | 语义索引 + 嵌入模型缓存 | | `CALIBRE_MCP_SEMANTIC_FLOOR` | `0.78` | 低于该值的语义结果被标记为低置信度 | | `CALIBRE_MCP_RERANK` | 开启 | 语义搜索的交叉编码器重排序阶段（~576 MB 模型，每次查询数秒 CPU）；设置为 `off`/`false`/`0` 以禁用 | | `CALIBRE_MCP_MAX_BOOK_BYTES` | `268435456`（256 MB） | `calibre_build_index` / `calibre_get_content` 将提取的最大图书下载量；较大的图书被跳过² | | `CALIBRE_MCP_ADD_ROOTS` | `~/Documents`，`~/Downloads` | `calibre_add_book` 可以导入的文件夹（路径分隔符分隔） | | `CALIBRE_MCP_BOARD_STYLE` | `shelf` | MCP 应用中的搜索结果小部件样式：`shelf`（滚动封面架）或 `coverflow`（3D 封面流；桌面捆绑包将其公开为 *Coverflow 搜索结果* 开关） | ¹ macOS `~/Library/Application Support/calibre-mcp/index`，Windows `%APPDATA%\calibre-mcp\index`，Linux `$XDG_DATA_HOME/calibre-mcp/index`。 ² 大小上限针对 **内容服务器提供的内容**，而不是磁盘上的文件 - 它可以返回一个更重的副本（一个 8 MB PDF 作为 70 MB 提供），因此磁盘大小上限会默默地跳过图书。 ## 🩺 故障排除 > 更多症状和修复方法：[`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)。 - **“Calibre 无法访问” / 连接被拒绝** — 内容服务器未运行。在 Calibre 中：*连接/共享 → 启动内容服务器*，或将 `CALIBRE_MCP_SERVER_URL` 指向正确的宿主/端口。 - **写入被拒绝 / “禁止”** — 内容服务器不允许本地写入。参见上面的 *启用写入*：运行一个独立的服务器，带有 `--enable-local-write`，或者在 GUI 的 *网络共享 → 高级* 选项中勾选，然后重启内容服务器。 - **全文搜索返回空结果 / 错误** — Calibre 的 FTS 索引未针对库启用。在 Calibre 中：*首选项 → 搜索 → 全文搜索*，启用它，并让索引完成（对于大型库可能需要一段时间）。 - **“嵌入模型不可用”** — 可选的 `@huggingface/transformers` 包未安装（使用 MCPB 捆绑包时预期）。使用 npx 安装，或在服务器旁边运行 `npm install @huggingface/transformers`。要搜索而不使用它，请构建一个仅限关键词的索引（`calibre_build_index keywordOnly=true`），并使用 `mode: keyword`。 - **`calibredb` 未找到** — 安装 Calibre，或将 `CALIBRE_MCP_CALIBREDB_PATH` 设置为二进制文件（macOS：`/Applications/calibre.app/Contents/MacOS/calibredb`）。 - **PDF 提取为空文本** — 它是一个扫描/图像 PDF；Calibre 没有 OCR，我们也没有。 - **库未找到（404）** — 传递库的 *显示名称* 或 *ID*，如 `calibre_list_libraries` 所示；如果不确定，请不要设置库，让服务器选择其默认值。 ## 🛠️ 开发 ```sh pnpm install pnpm build # tsc → dist/ pnpm test # vitest（单元测试；无网络，无模型下载） pnpm test:model # 受限的嵌入模型集成测试（~118 MB 下载） pnpm inspect # MCP 检查器针对已构建的服务器 pnpm pack:mcpb # 构建 Claude Desktop .mcpb 捆绑包 ``` 代码库是清洁架构：工具处理程序、Calibre 客户端和语义核心是无 SDK 的；只有 `src/server.ts` 触及 MCP SDK。用户文档 - 工具参考和语义搜索指南 - 位于 [`docs/`](./docs)。 在 [**讨论**](https://github.com/caelum29/calibre-mcp/discussions) 中欢迎提出问题、想法和设置；在 [问题](https://github.com/caelum29/calibre-mcp/issues) 中报告错误和 PR。 ## 📄 许可证 [MIT](./LICENSE) © 2026 Artem Sorochynskyi 一个独立项目，与 Calibre 无关。Calibre 本身是 [Kovid Goyal 的开源项目](https://github.com/kovidgoyal/calibre)（GPLv3）— 该服务器通过 `calibredb` 和内容服务器作为单独的程序驱动它。