calibreweb-mcp

一个只读的 Model Context Protocol 服务器，用于 Calibre-Web（以及 Calibre-Web Automated），即自托管的电子书库 Web 界面。

Calibre-Web 没有 REST API——其唯一稳定的机器可读接口是它为电子书阅读器应用提供的 OPDS 目录订阅源。此服务器使用该订阅源：通过 HTTP Basic 认证接收 Atom XML，输出结构化的图书数据。可搜索书库、浏览精选视图和书架、获取每种格式的下载链接，并将封面图片直接拉入对话中。它从不写入任何内容：每个工具都是针对 OPDS 路由的 GET 请求。

📖 完整文档：calibreweb-mcp.ni-c.de

要求

• Node.js 22 或更新版本

• 一个 Calibre-Web 实例（针对当前 linuxserver/calibre-web 镜像开发；Calibre-Web Automated 同样适用）

• 为服务器创建一个 Calibre-Web 用户。OPDS 订阅源使用常规 Web 登录进行认证——请使用仅具有查看和下载角色的专用账户，不要使用管理员账户。如果实例允许匿名浏览，服务器也可以在没有凭据的情况下运行。

Related MCP server: access-calibre

配置

¹ 如果实例允许匿名浏览，请将两者都留空；仅设置其中一个属于配置错误。

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 = "..." }

工具

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

图书条目包括作者、标签、丛书（含索引）、评分、摘要（有长度限制）、封面 URL 以及每种格式的下载 URL——这些是用户可以打开的现成链接，因为模型本身没有理由下载 EPUB。

分页

订阅源按实例的每页图书数设置（默认 60）进行分页；页面大小不受客户端控制。每个列表在存在更多页面时都会返回 pagination.nextOffset——在下次调用中将其作为 offset 传入。discover 视图是随机选择，不支持分页。

明确排除的范围

• 无写入操作。 OPDS 订阅源没有写入操作，此服务器也不会添加任何写入操作。

• 无文件下载。 工具返回下载 URL，而非电子书文件本身。

• 无分类浏览（作者/丛书/标签/出版社/语言/格式作为独立的索引订阅源）。search_books 涵盖了这些查找；相关路由已存在，如果有实际用例，可以为其添加工具。

安全性

• 服务器在设计上是只读的——仅发送 GET 请求，不保存任何状态。

• 图书元数据是来自第三方的不可信数据；每个结果都会说明这一点，控制字符会被剥离，并且 XML 实体处理已被禁用（声明了 DOCTYPE 或实体的文档会被直接拒绝）。

• 响应在解析前有大小限制（订阅源 8 MB，封面 1 MB），在到达模型前再次限制（每本书和每次响应的预算）。

• 订阅源中的 href 仅在解析为配置的源站且使用 http(s) 协议时才会被传递——恶意订阅源无法将 javascript:、file: 或跨域 URL 植入结果中。

• 重定向被拒绝，以确保 Basic 凭据永远不会被重放到其他主机；封面仅在内容类型为真实图片时才被传递。

• 密码在启动时从进程环境中清除，URL 中的凭据会在出现在任何日志或结果中之前被删除。

容器

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

开发

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

许可证

MIT