Calibre-Web

calibreweb-mcp

一个适用于 Calibre-Web（以及 Calibre-Web Automated）的只读 模型上下文协议（MCP）服务。Calibre-Web 是一款可自托管的电子书库 Web 界面。

MCP 客户端（如 Claude Code、Claude Desktop 或 Codex）可以借助它搜索书库、浏览精选视图和书架、使用各格式的下载链接，并将封面图片直接载入对话。它绝不会写入任何内容：每个工具都只发起 GET 请求。

工具数量上限是 6 个，而非必须达到 6 个：设置 CALIBRE_WEB_ALLOW_TOOLS=essential 可改为注册精选的 5 个工具。模型从 5 个工具中选择正确工具的可靠性远高于从 6 个中选择，详情请参阅选择要加载的工具。

Calibre-Web 没有 REST API；它唯一稳定、可供机器读取的接口，是为电子阅读器应用提供的 OPDS 目录源。本服务使用该目录源：传入 Atom XML 和 HTTP Basic 身份验证，传出结构化书籍数据。

特点

Calibre-Web 从未提供过的 API。 Calibre-Web 不提供 REST API；其唯一稳定的机器接口是为电子阅读器应用构建的 OPDS Atom 源。这些工具会将该源解析为结构化书籍数据，其中包含数字 ID、各格式的下载 URL 和长度受限的摘要。

从设计上确保只读。 这 6 个工具都只发起 GET 请求。服务会拒绝重定向，以免 Basic 凭据被传送；直接拒绝包含 DOCTYPE 的 XML；将 href 限定在配置的源站内；并将元数据标记为不可信数据。

要求

• Node.js 22 或更高版本
• 一个 Calibre-Web 实例（基于当前的 linuxserver/calibre-web 镜像开发；Calibre-Web Automated 的使用方式相同）
• 一个供服务使用的 Calibre-Web 用户。OPDS 源使用常规 Web 登录进行身份验证，请使用仅具有 View 和 Download 角色的专用账户，不要使用管理员账户。如果实例允许匿名浏览，服务也可以不配置凭据运行。

配置

变量	必需	描述
CALIBRE_WEB_URL	是	实例的根 URL，例如 https://books.example.com。系统会自动追加 /opds 路径。
CALIBRE_WEB_USERNAME	是¹	Calibre-Web 账户的用户名。
CALIBRE_WEB_PASSWORD	是¹	该账户的密码（网页登录密码）。
CALIBRE_WEB_INSECURE_TLS	否	设为 true 以接受自签名证书——仅适用于配置的主机。
CALIBRE_WEB_ALLOW_TOOLS	否	以逗号分隔的工具名称、list_* 前缀，或用于精选预设的 essential
CALIBRE_WEB_DENY_TOOLS	否	语法相同；从 CALIBRE_WEB_ALLOW_TOOLS 保留的工具中移除指定工具

¹ 对于允许匿名浏览的实例，两项都留空；只设置其中一项会导致配置错误。

选择要加载的工具

CALIBRE_WEB_ALLOW_TOOLS 和 CALIBRE_WEB_DENY_TOOLS 接受以逗号分隔的工具名称； 名称末尾的 * 可匹配整个工具系列。essential 是包含以下五个工具的精选预设： search_books、list_books、list_shelves、get_shelf_books、get_stats。

CALIBRE_WEB_ALLOW_TOOLS=essential
CALIBRE_WEB_ALLOW_TOOLS=search_books,list_shelves
CALIBRE_WEB_DENY_TOOLS=get_cover

如果某个条目未匹配到任何工具，启动会中止并指出该条目，因此拼写错误不会悄悄隐藏工具——没人会把缺失的工具追溯到某个环境变量。如果工具被过滤，就永远不会注册，因此它既不会出现在 tools/list 中，也无法通过 tools/call 调用。

如果你同时运行多个此类服务，mcp-hub 是另一种选择——它的 /hub 端点会用六个元工具替换每个服务的所有工具。

安装

Claude Code

claude mcp add calibreweb \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  -- npx calibreweb-mcp

Claude Desktop

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["calibreweb-mcp"],
      "env": {
        "CALIBRE_WEB_URL": "https://books.example.com",
        "CALIBRE_WEB_USERNAME": "reader",
        "CALIBRE_WEB_PASSWORD": "..."
      }
    }
  }
}

Codex

[mcp_servers.calibreweb]
command = "npx"
args = ["calibreweb-mcp"]
env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }

Docker

docker run -i --rm \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  ghcr.io/ni-c/calibreweb-mcp

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Claude 网页版、Cursor、LibreChat——可通过 mcp-hub 连接 calibreweb-mcp：一个容器通过 Streamable HTTP 为多个 stdio MCP 服务提供服务，并在单个密码后提供 OAuth 2.1 登录，以及为无法使用 OAuth 的客户端提供长期有效的令牌。它的 /hub 端点会用六个元工具将所有服务置于其后，因此一个连接器即可访问所有服务，无需在模型上下文中放入 N×工具架构；它还支持两个协议修订版本——本服务提出的问题会经由它传递给另一端的用户。

它的 /config/mcp.json 使用 Claude Code 的格式，因此条目就是你已有的那个：

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["-y", "calibreweb-mcp"],
      "env": { "CALIBRE_WEB_ALLOW_TOOLS": "essential" },
      "denyTools": ["get_cover"]
    }
  }
}

其中的 allowTools 和 denyTools 是 hub 自身针对每个服务的过滤器，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别以及由此可能引发的误用，详见客户端指南。

工具

所有工具均为只读（readOnlyHint: true）。

工具	描述
search_books	按书名、作者、丛书、出版商和标签搜索。Calibre-Web 一次返回所有匹配项；结果由客户端限制数量（limit，默认 50），并报告实际匹配数。
list_books	按视图列出图书：new（默认）、hot、rated、discover（随机）、read、unread 或 all（可选按首字母缩小范围）。
list_shelves	公共书架以及已配置用户自己的书架。
get_shelf_books	书架上的图书，按书架顺序排列。
get_cover	图书封面，以客户端可显示的图像形式返回。
get_stats	图书、作者、分类和丛书的总数。

图书条目包含作者、标签、丛书（含序号）、评分、长度受限的摘要、封面 URL 和各格式的下载 URL——这些都是人类可以打开的现成链接，因为模型本身无需下载 EPUB。

结构化输出

每个工具都声明了 outputSchema，并在文本块之外通过 structuredContent 返回结果，因此客户端无需解析文本即可使用结果：

{
  "untrusted": true,
  "source": "calibre-web",
  "totalFound": 2,
  "truncated": false,
  "books": [{ "id": 7, "title": "Dune", "authors": ["Frank Herbert"] }],
  "notes": ["Book titles, authors, tags, series and summaries come from …"],
}

untrusted 标记是一个字段，而不只是 notes 中的一行，因为读取结构化内容的客户端否则就必须在一组句子中寻找警告。没有此标记的两个工具分别是 get_stats 和 get_cover：前者返回四个计数器，本服务已确认它们都是数字；后者报告一个 id、一种来自四项允许列表的媒体类型，以及字节数——图像本身仍保留在客户端渲染的内容块中。

超出预算的结果仍会像以前一样省略图书摘要。如果这样仍不够，现在会返回错误，而不是被截断到上限的 JSON：无法解析的文本在文本块中尚可接受，但 structuredContent 无法承载；两个通道必须包含相同的值。

分页

信息流按实例的 每页图书数 设置分页（默认 60）；客户端无法控制每页大小。每个列表在有更多页面时都会返回 pagination.nextOffset——在下一次调用中将其作为 offset 传入。discover 视图是随机选择，不分页。

有意不公开的功能

• 不支持写入。 OPDS 信息流不支持写入，本服务也不会添加此功能。
• 不支持下载文件。 工具返回下载 URL，而非电子书内容。
• 不支持按类别浏览（作者／丛书／标签／出版商／语言／格式的独立索引信息流）。search_books 可满足这些查询需求；相应路由已存在，如果有实际使用场景，也可以为它们添加工具。

安全性

• 该服务从设计上就是只读的——仅处理 GET 请求，不会在任何地方保存状态。
• 图书元数据属于不可信的第三方数据；每条结果都会注明这一点，控制字符会被剥除，并且会禁用 XML 实体处理（声明了 DOCTYPE 或实体的文档会被直接拒绝）。
• 在解析前会限制响应大小（Feed 为 8 MB，封面为 1 MB），在发送给模型前还会再次限制（按图书和按响应分别设置预算）。
• 仅当 Feed 的 href 通过 http(s) 解析到已配置的来源时，才会传递该 href——恶意 Feed 无法将 javascript:、file: 或跨来源 URL 注入结果。
• 系统会拒绝重定向，因此 Basic 凭据绝不会被重放到其他主机；仅当封面内容类型确实为图像时，才会传递封面。
• 启动时会从进程环境中清除密码，并在 URL 出现在任何日志或结果之前对凭据进行脱敏。

文档

完整指南、工具参考和安全说明请访问 calibreweb-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm test            # unit tests against a stubbed OPDS feed, no instance needed
npm run lint
npm run build

请参阅 CONTRIBUTING.md。

发布

1. 更新 CHANGELOG.md，并更新 package.json 中的版本号（以及锁定文件）。
2. npm run lint && npm run test:coverage && npm run build
3. 为发布打标签：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道， 而不要公开提交问题；相关政策请参阅 SECURITY.md。

许可证

MIT © Willi Thiel