AI导哈

电子书库管理服务

Calibre MCP Server 是一个提供本地 Calibre 电子书库接口的服务，支持搜索、获取详情、添加和转换电子书等功能，适用于AI代理和开发工具集成。

  • by Quentinbest
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Quentinbest/calibre_mcp

使用说明

Calibre MCP服务器

英语 | 中文

一个模型上下文协议（MCP）服务器，为您的本地提供接口 卡利伯 图书馆。这允许AI代理（如Claude或Cursor）在Calibre库中搜索、检索详细信息、添加和转换书籍。

特性

  • 搜索书籍：按标题、作者或其他元数据查询您的库。
  • 获取详细信息：检索特定书籍的完整元数据，包括可用格式和文件路径。
  • 添加书籍：从本地文件系统向库中添加新书文件。
  • 转换书籍：使用Calibre在格式之间转换书籍（例如，EPUB到MOBI） ebook-convert 工具。

先决条件

  • Python 3.10+
  • 卡利伯：The calibredb 和 ebook-convert 命令行工具必须在系统PATH中安装并可访问。
    • 在macOS上，这些通常可以在 /Applications/calibre.app/Contents/MacOS/ 或链接到 /usr/local/bin 或 /opt/homebrew/bin.
    • 通过运行验证安装 calibredb --version 在你的终端。

安装

  1. 克隆或复制存储库: 确保你有 calibre_mcp 目录和 requirements.txt.

  2. 安装依赖项: 建议使用虚拟环境。

    pip install -r requirements.txt

配置

如果Calibre库不在默认位置，服务器需要它的路径。

  • 环境变量: CALIBRE_LIBRARY_PATH
    • 例子： /Users/username/Calibre Library

用法

您可以直接运行服务器进行测试，但它被设计为由MCP客户端运行。

手动运行（用于测试）

# Optional: Set library path
export CALIBRE_LIBRARY_PATH="/path/to/your/library"

# Run the server
python3 server.py

使用Docker运行

  1. 塑造形象:

    docker build -t calibre-mcp .

  2. 运行容器: 您需要将Calibre库装载到容器中。

    docker run -i --rm \
  -v "/path/to/your/library:/library" \
  -e CALIBRE_LIBRARY_PATH="/library" \
  calibre-mcp

    或者使用Docker Compose：

    export CALIBRE_LIBRARY_PATH="/path/to/your/library"
docker-compose up --build

    注意：当与Claude Desktop等MCP客户端一起使用时，您需要配置客户端以运行 docker run 命令。看 Docker安装指南 了解详细的配置说明。

客户端配置

克劳德桌面

将以下内容添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "calibre": {
      "command": "/path/to/python3",
      "args": [
        "/absolute/path/to/calibre_mcp/server.py"
      ],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/Calibre Library"
      }
    }
  }
}

注：更换 /path/to/python3 使用实际的Python可执行路径（运行 which python3 找到它）。

光标

  1. 首选 光标设置 > 特性 > 主控程序.
  2. 点击 添加新的MCP服务器.
  3. 名字：口径
  4. 类型标准： stdio
  5. 命令: /path/to/python3 （例如。， /usr/bin/python3 或从你的venv）
  6. 参数: /absolute/path/to/calibre_mcp/server.py
  7. 环境变量:
    • 密钥： CALIBRE_LIBRARY_PATH
    • 价值： /absolute/path/to/Calibre Library

工具参考

工具 描述 参数 返回
search_books 在图书馆找书。 query （string）：搜索查询（例如。， title:Python) 书籍列表(id, title, authors)
get_book_details 获取特定书籍的详细元数据。 book_id （int）：Calibre图书ID 带完整元数据的词典
add_book 将新文件添加到库中。 file_path （string）：文件的绝对路径 带有新图书ID的成功消息
convert_book 将书籍转换为其他格式。 book_id （int）， output_format （string） 成功消息
delete_book 从图书馆永久删除一本书。 book_id （int） 状态消息
export_book 将书籍导出到特定目录。 book_id （int）， output_dir （字符串） 状态消息
update_book 更新图书元数据。 book_id （int）， title （str，opt）， authors （str，opt） 状态消息
manage_tags 在书中添加或删除标签。 book_id （int）， add_tags （列表）， remove_tags （列表） 状态消息
set_cover 设置书籍的封面图像。 book_id （int）， cover_path （字符串） 状态消息
get_cover_path 获取本书封面图片的本地路径。 book_id （int） 覆盖图像的绝对路径
read_book_content 阅读一本书的文本内容。 book_id （int） 文本内容（如果较大，则截断）
list_categories 列出可用类别。 category_type （string）：例如。， tags, authors 类别名称列表
check_library 对库运行一致性检查。 无 检查报告
get_library_stats 获取图书馆的统计数据。 无 统计字典

故障排除

  • calibredb executable not found：确保目录包含 calibredb 在您的系统PATH中，或者您正在使用正确的环境变量启动MCP客户端。
  • Book not found：使用验证图书ID search_books.
  • 转换失败：确保 ebook-convert 已安装。某些转换（例如，DRM保护的文件）可能会失败。

相关 MCP