Calibre MCP Server

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

配置架构参考

每个库都由一个唯一的文本键标识，并且可以有自己单独的配置值：

还有几个顶级配置设置适用于整个MCP服务器：

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": ""
            }
        }
    }
}

*（注意：如果您已在本地克隆了存储库，并希望从本地副本运行，则可以替换 "github.com/FaceDeer/calibre_full_mcp_server" 随着 ``.)*

这应该允许您通过选择要指向的配置，根据需要轻松切换不同代理的库配置 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数据库交互，请参阅 架构文档.