一个用于现有 Calibre 电子书库的只读 Model Context Protocol 服务器。
Calibre MCP 让兼容 MCP 的客户端能够搜索图书元数据、查询 Calibre 的全文索引、查看图书详情、浏览书库分类以及发现相关图书。它使用 Calibre 支持的 calibredb 命令行界面，而不是直接读取 metadata.db。
使用 Calibre 搜索语言的元数据搜索
带匹配摘要的全文搜索
单本图书的详细元数据
最近添加的图书
作者、标签、丛书、出版社和语言分类
相关图书发现
用于图书、搜索和书库状态的 MCP 资源
可选的 Calibre Content Server 链接
内存 TTL 缓存
Streamable HTTP 传输
Podman Quadlet 部署
无修改元数据的 MCP 工具
Related MCP server: calibre-manager
工具 | 用途 |
| 显示服务器、Calibre、缓存和书库配置 |
| 显示图书数量和全文索引状态 |
| 搜索 Calibre 元数据 |
| 在已索引的电子书中搜索并返回摘要 |
| 返回单本图书的所有可用元数据 |
| 列出最近添加的图书 |
| 浏览作者、标签、丛书、出版社和语言 |
| 查找具有相同作者、丛书或标签的图书 |
| 清除内存中的读取缓存 |
URI | 用途 |
| 书库和全文索引状态 |
| 单本图书的详细元数据 |
| 元数据搜索结果 |
一个包含 metadata.db 的 Calibre 书库
Calibre 9.x
Python 3.11 或更高版本
支持 Streamable HTTP 的 MCP 客户端
用于随附 Quadlet 部署的 Podman 和 systemd
全文工具要求 Calibre 的全文索引已启用并完成构建。
git clone https://github.com/monch1962/calibre-mcp.git
cd calibre-mcp随附的 Quadlet 假定：
/tank/media/Books确认书库数据库存在：
test -f /tank/media/Books/metadata.db && echo "Calibre library found"stat -c 'uid=%u gid=%g owner=%U:%G' /tank/media/Books编辑 quadlet/calibre-mcp.container，将 User= 设置为返回的数字 UID 和 GID：
User=1000:1000如果你的主机书库路径不同，也请一并修改：
Volume=/tank/media/Books:/bookssudo podman build \
--build-arg CALIBRE_VERSION=9.11.0 \
-t localhost/calibre-mcp:1.0.0 .sudo mkdir -p /etc/containers/systemd
sudo cp quadlet/calibre-mcp.container \
/etc/containers/systemd/calibre-mcp.container
sudo systemctl daemon-reload
sudo systemctl start calibre-mcp.service不要运行 systemctl enable calibre-mcp.service。生成的服务是临时的；Quadlet 的 [Install] 部分会创建开机依赖。
sudo systemctl status calibre-mcp.service --no-pager
sudo journalctl -u calibre-mcp.service -n 100 --no-pager
sudo podman ps --filter name=calibre-mcp验证容器内的 Calibre：
sudo podman exec calibre-mcp \
calibredb list \
--with-library /books \
--for-machine \
--fields title \
--limit 1
sudo podman exec calibre-mcp \
calibredb fts_index status \
--with-library /books默认端点为：
http://localhost:8008/mcpnpx @modelcontextprotocol/inspector选择 Streamable HTTP 并连接到：
http://YOUR_SERVER:8008/mcp元数据搜索示例：
{
"query": "author:asimov",
"limit": 10
}全文搜索示例：
{
"query": "zero trust architecture",
"limit": 10
}受限全文搜索示例：
{
"query": "encryption",
"limit": 10,
"restrict_to": "search:tags:security"
}使用服务器暴露的 Streamable HTTP 端点：
http://YOUR_SERVER:8008/mcp客户端配置格式各不相同。请查阅你所用客户端的 MCP 文档，并选择 Streamable HTTP，而不是 stdio 或旧版 SSE。
search_books 接受 Calibre 搜索表达式：
author:asimov
title:"i robot"
tags:history
series:"Discworld"
publisher:penguin
languages:eng
rating:>=4空查询将返回所有图书，但受结果数量限制。
在 Quadlet 中设置你现有 Calibre Content Server 的 URL：
Environment=CALIBRE_CONTENT_SERVER_URL=http://mini-nas:8083配置后，元数据结果将包含浏览器和格式下载链接。
环境变量 | 默认值 | 描述 |
|
| 容器内的 Calibre 书库 |
|
| Calibre CLI 的路径 |
|
| 命令超时时间（秒） |
|
| 工具返回的最大结果数 |
|
| 缓存生命周期（秒）；设为 |
|
| 最大缓存条目数 |
|
| 最大并发 |
| unset | 可选的 Content Server 基础 URL |
|
| MCP HTTP 绑定地址 |
|
| 容器内的 MCP 端口 |
|
| Calibre 配置的可写位置 |
Calibre 会通过在书库根目录中短暂创建并删除一个探测文件来检查书库文件系统是否区分大小写。因此，绑定挂载不能以只读方式挂载。
该服务器在功能上仍保持只读，因为它不暴露任何调用 Calibre 命令的工具，例如：
add
remove
set_metadata
add_format
remove_format
请以拥有书库的同一非特权 UID 和 GID 运行容器。除非你的环境特别要求，否则不要以 root 身份运行。
将端口 8008 限制为仅受信任的 LAN 或 Tailscale 客户端可访问。
不要将端点直接暴露到公共互联网。
在此部署中，Streamable HTTP 不添加身份验证。
在更广泛暴露之前，在服务前放置经过身份验证的反向代理。
固定发布版本，而不是使用变动的容器标签。
在报告漏洞之前，请查阅 SECURITY.md。
十个对抗性攻击向量通过失败的测试得到证实，然后被修复。
tests/attack_round1_test.py 中的每个 TestAttack_* 测试都是其对应向量的永久回归测试夹具。
# | 攻击向量 | 入口点 | 防御 |
1 | 无界缓存键——每个缓存条目在内存中保留一个数兆字节的查询 |
| 超过 512 字节的键使用 SHA-256 哈希（ |
2 | 无界缓存值——每个条目保留大量 |
| 超过 1 MiB 的值绕过缓存（ |
3 |
|
| 已应用超时； |
4 | 无效 |
|
|
5 | 非数字 book-id 键上未处理的 |
| 已包装 → |
6 | 通过书库元数据进行的搜索语法注入——作者、丛书或标签中的引号/反斜杠会突破生成的查询 |
|
|
7 | 无界查询长度——MB 级查询到达 |
| 超过 8192 个字符的查询以 |
8 | 并发洪泛下无界的瞬时 |
| 残余风险——受 |
9 |
| 部署 | 已接受的安全姿态——在 SECURITY.md 中记录 |
10 | 信息泄露——书库路径、Calibre 版本 |
| 对于只读知识服务器已接受；已记录 |
本轮已验证的安全表面：shell 注入（使用参数列表，无 shell=True）、选项值注入（Calibre 解析器拒绝 --sort-by/--categories/--restrict-to 中以破折号开头的值）、资源 URI 路径遍历（拒绝非数字 id）、结果数量限制（_limit）以及缓存竞态条件（由锁保护）。
六个输入形态验证向量已得到证实并修复；测试夹具位于 tests/attack_round2_test.py。
# | 攻击向量 | 入口点 | 防御 |
11 | 无界的 |
|
|
12 | 无界的 |
| 1024 字符上限 → |
13 | 无界的 |
| 2048 字符上限 → |
14 | 无界的 |
| 128 字符上限 → |
15 | 不可迭代的 |
| 非列表/元组的 formats 被忽略；仍返回 |
16 | 生成的下载链接中的格式扩展注入（ |
| 扩展名白名单 |
三个错误路径鲁棒性攻击向量已证实并修复；测试夹具位于 tests/attack_round3_test.py。
# | 攻击向量 | 入口点 | 防御 |
17 | 超大 CSV 字段（超过 128 KiB 的 csv 字段大小限制）→ 原始 |
| 迭代已包装 → |
18 |
|
| 拒绝非 dict 的数组项 → |
19 |
|
| 每个列表值键都被切片到结果上限 |
两个并发/进程洪泛攻击向量已证实并修复；测试夹具位于 tests/attack_round4_test.py。
# | 攻击向量 | 入口点 | 防御 |
20 | 并发 |
|
|
21 |
|
| 版本调用通过同一信号量路由（ |
零新增漏洞。一次覆盖缺口审计新增了 11 个验证测试（tests/attack_round5_test.py），覆盖了第 1–4 轮尚未触及的每个入口点 — search_resource、book_resource（非数字、类路径遍历、范围内）、status_resource、library_status、list_recent_books、clear_cache、search_fulltext 列表载荷、零/负限制、TTL 为零的缓存禁用，以及空白查询。所有测试均立即通过，确认第 1–4 轮的防御在整个工具/资源表面上依然有效。
两个与部署态势相关的文档发现已记录在 SECURITY.md 中（无代码更改）：Containerfile 没有 USER 指令（在 Quadlet 之外构建时以 root 运行，而 Quadlet 设置了 User=1000:1000），并且 Quadlet 设置了 SecurityLabelDisable=true（SELinux 标签隔离已关闭）。
创建虚拟环境：
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest ruff运行测试：
pytest运行 lint 检查：
ruff check .在本地启动服务器：
export CALIBRE_LIBRARY_PATH="/path/to/Calibre Library"
python server.py版本 1.0.0 适用于个人和可信网络部署。公共 API 可能会在未来的次要版本中增加更多工具和资源，同时现有的工具名称和参数形状将在可行的情况下保持稳定。
欢迎提交 Issue 和 Pull Request。请参阅 CONTRIBUTING.md。
根据 MIT 许可证 发布。
This server cannot be deployed
MCP server for Project Gutenberg — 75,000+ public-domain ebooks with full plain-text retrieval.
MCP server for Russian books search, details, and recommendation candidates.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Read-only MCP server for verified book recommendations and reading lists.
