使用说明
Calibre MCP服务器
此MCP服务器弥合了AI代理和您的 卡利伯 电子书图书馆。它使代理能够作为一个动态知识库与您的收藏进行交互，使他们能够搜索、管理和阅读您的数字图书馆。与其他MCP服务器不同，如果库的权限设置为允许，它还可以允许AI代理更新库元数据和内容。
主要特点
-
高级搜索： 使用图书元数据查询库或执行全文内容搜索。
-
元数据管理： 查看和更新任何书籍的元数据（标题、作者、标签、评级等）。
-
图书馆维护： 向收藏中添加新标题或删除现有标题。
-
格式转换： 利用Calibre强大的转换引擎在电子书格式（例如PDF到EPUB）之间动态切换。
-
直接阅读： 直接在代理的上下文窗口中搜索并阅读书籍的文本内容，以进行分析、总结或问答。
-
精细权限： 为每个库定义严格的访问控制，包括只读模式和字段级写入限制。
先决条件
-
口径： 必须安装在主机系统上。此服务器利用
calibre-debug以执行工作进程。 -
并发注意事项： Calibre不支持对单个库的并发访问。 不要 将代理指向Calibre桌面应用程序或其他Calibre进程当前使用的库，以避免数据库损坏。设置a
worker_timeout可以降低意外发生这种情况的风险，但不要依赖它来保护你的库。注意你在做什么。
配置
服务器是通过JSON文件配置的。由于JSON不支持注释，请使用以下结构作为模板。
配置示例(config.json)
JSON
{
"libraries": {
"default": {
"path": "d:/ebooks/main_library",
"description": "The primary research library containing technical manuals.",
"default": true,
"permissions": {
"read": ["title", "authors", "tags", "rating", "comments"],
"write": ["tags", "rating", "comments"],
"delete": false,
"convert": true
},
"import": {
"allowed_paths": ["d:/downloads/ebook_imports"],
"allow_delete_source": false
},
"export": {
"allowed_paths": ["d:/ebook_exports"s],
"allow_overwrite_destination": false
},
"worker_timeout": 300
}
},
"port": 8000,
"enable_worker_logging": false,
"expose_resources_via_tools": true,
"log_level": "warning"
}
配置架构参考
每个库都由一个唯一的文本键标识，并且可以有自己单独的配置值：
| 钥匙 | 描述 |
|---|---|
path |
Calibre库的绝对路径（其中 metadata.db 居住）。 |
description |
提供给代理的自由形式上下文，解释此库包含什么或其目的是什么 |
default |
如果 true，如果没有特定的库作为目标，则代理将使用此库。如果只配置一个库，那么这是不必要的。 |
permissions.read |
设置为 true （所有字段均已显示）， false（对于只写库，如果你需要的话），或特定字段的列表（例如。， ["title", "authors"]). |
permissions.write |
允许代理修改的元数据字段列表true适用于所有领域和 false对于只读库。 |
permissions.delete |
布尔值。如果 false，代理无法从库中删除书籍。 |
permissions.convert |
布尔值。允许代理通过转换现有格式向图书记录添加新格式。如果 false服务器仍然可以转换书籍以供内部使用或导出，但它不会将转换后的文件添加到图书馆书籍记录中。 |
import.allowed_paths |
代理可以从中导入新文件的目录白名单。 |
import.allow_delete_source |
如果 true，服务器可以在成功导入后删除原始文件。 |
export.allowed_paths |
代理可以将图书文件导出到的目录的白名单 |
export.allow_overwrite_destination |
如果 true，服务器在导出文件时可以覆盖允许导出路径中的文件。 |
worker_timeout |
以秒为单位的整数。这个特定的图书馆 calibre-debug如果经过这么长时间没有活动，worker进程将结束。如果省略，则默认为的根配置 worker_timeout. |
还有几个顶级配置设置适用于整个MCP服务器：
| 密钥 | 描述 |
|---|---|
port |
服务器暴露的端口 |
enable_worker_logging |
每个Calibre库都有自己的 calibre-debug运行代码和内部Calibre API交互的过程。当 true这些进程将把日志写入 logs用于调试目的的文件夹。 |
worker_timeout |
为了提高效率 calibre-debug每个库的工作进程在请求之间保持活动状态。Calibre不会同时处理访问同一库的多个进程，因此为了降低发生这种情况的风险，您可以为非活动工作进程设置超时（以秒为单位）以使其过期。如果没有设置，则只要服务器启动，进程就会保持活动状态（除非被特定库的配置覆盖）。 |
log_level |
设置记录消息的最低级别 logs/app.log。设置为“错误”、“警告”、“信息”、“调试”或“无”。 |
expose_resources_via_tools |
一些较旧的MCP客户端不理解此服务器公开的“资源”类型，例如允许代理读取 /skills文件夹。当此设置为 true这些资源将通过以下方式暴露 list_help_topics和 get_help_topic相反。这 libraries列出可用库及其权限的资源也将转换为 list_libraries工具。 |
MCP配置示例
您可以使用以下命令运行此MCP服务器 uvx，它将从GitHub无缝下载并运行最新版本，而无需手动安装。
第一， 安装uv 如果你还没有。
然后，指向您的配置文件 CALIBREMCP_CONFIGPATH MCP客户端配置中的环境变量。例如：
JSON
{
"mcpServers": {
"calibre": {
"command": "uvx",
"args": [
"--from",
"github.com/FaceDeer/calibre_full_mcp_server",
"calibre-full-mcp"
],
"env": {
"CALIBREMCP_CONFIGPATH": "<full path to your config.json>"
}
}
}
}
（注意：如果您已在本地克隆了存储库，并希望从本地副本运行，则可以替换 "github.com/FaceDeer/calibre_full_mcp_server" 随着 <full path to your local repository directory>.)
这应该允许您通过选择要指向的配置，根据需要轻松切换不同代理的库配置 CALIBREMCP_CONFIGPATH at。
提高性能的专业提示
1.优化现场访问
Calibre库通常包含内部元数据，这可能会使代理的上下文窗口变得混乱。它是 强烈推荐 使用特定列表 read 权限。仅公开代理实际需要的字段（例如，标题、作者、标签、注释）。
2.自定义字段和系列
-
自定义字段： 如果在Calibre中使用自定义列，则必须包含
#前缀（例如。，#my_custom_field). -
系列： 每个
series字段具有相应的series_index。如果您希望代理查看或管理系列中的图书订单，请确保两者都包含在您的权限列表中。 -
描述： 服务器将自定义字段“描述”传递给代理。在Calibre中使用这些提示，为代理提供如何使用特定自定义列的提示。例如，如果你为一本书的“年龄评级”创建了一个自定义字段，你可以使用描述来解释该字段的值代表什么。
3.资源风险
如果你的代理人还不支持 @mcp.resources 标准，套 expose_resources_via_tools 到 true。这将公开专用工具，允许代理通过标准工具调用获取文件。
Docker支持
如果您正在为此服务器构建Docker映像，建议在构建阶段预先下载必要的NLTK模型，以避免运行时下载和启动缓慢。
您可以使用提供的安装脚本来实现此目的：
# Inside your Dockerfile
RUN calibre-full-mcp-setup
这将下载 punkt 和 punkt_tab 将模型放入图像中。
建筑
要深入了解此服务器如何管理工作进程并与Calibre数据库交互，请参阅 架构文档.
