AI导哈

电子书元数据服务

Calibre MCP Server是一个通过MCP协议提供电子书库搜索和元数据检索的工具。

  • by ajtudela
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ajtudela/calibre_mcp_server

使用说明

Calibre MCP 服务器

一个MCP（模型上下文协议）服务器，它提供了与Calibre电子书库交互的工具，允许通过MCP协议搜索和检索书籍的元数据。

工具

工具 描述 参数
按书名搜索书籍 使用通配符按标题模式搜索书籍 title_pattern: str
按名称搜索作者 通过通配符按名称模式搜索作者 name_pattern: str
按作者获取书籍 获取特定作者的所有书籍 author_name: str
按作者ID获取书籍 获取特定作者ID的所有书籍 author_id: int
按系列获取书籍 获取系列中的所有书籍，按索引排序 series_name: str
按标签获取书籍 获取所有带有特定标签的书籍 tag_name: str
按标签模式搜索书籍 使用通配符按标签模式搜索书籍 tag_pattern: str
获取书籍详情 获取特定书籍的完整详情 book_id: int
获取库统计信息 获取全面的图书馆统计数据 —
获取所有标签 获取库中所有可用的标签 —

配置

服务器支持通过环境变量进行灵活配置：

变量 默认值 描述
CALIBRE_LIBRARY_PATH — （无对应中文翻译，此符号通常表示分隔或空位） 必需的 Calibre 图书库的路径
CALIBRE_DB_FILENAME metadata.db 库内的数据库文件名
LOG_LEVEL INFO 日志级别 (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT 默认格式 自定义日志格式字符串
MCP_SERVER_NAME Calibre MCP Server MCP协议的服务器名称
TRANSPORT_MODE stdio 交通方式（stdio 或者 http）
HTTP_HOST 0.0.0.0 使用HTTP传输时的HTTP主机
HTTP_PORT 9001 使用HTTP传输时的HTTP端口

环境设置

  1. 复制示例环境文件：
cp .env.example .env
  1. 编辑 .env 根据您的设置：
# Required
CALIBRE_LIBRARY_PATH=/path/to/your/calibre/library

# Optional
LOG_LEVEL=DEBUG
TRANSPORT_MODE=http

特点/功能

  • 高级搜索功能按标题、作者、系列和标签搜索书籍，支持通配符
  • 全面的元数据检索完整的书籍信息，包括出版日期、系列信息和标签
  • 图书馆统计通过全面的统计数据深入了解您的Calibre图书馆
  • 标签管理浏览并搜索您库中所有可用的标签
  • 作者发现查找作者并探索他们的完整参考书目
  • 系列追踪按系列索引正确排序访问系列书籍

安装

使用uv进行安装（推荐）

克隆仓库并使用 uv 进行安装：

git clone https://github.com/ajtudela/calibre_mcp_server.git
cd calibre_mcp_server
cp .env.example .env
# Edit .env file with your Calibre library path
uv sync

或者直接从仓库安装：

uv add git+https://github.com/ajtudela/calibre_mcp_server.git

使用 pip 安装

以以下模式安装软件包：

git clone https://github.com/ajtudela/calibre_mcp_server.git
cd calibre_mcp_server
cp .env.example .env
# Edit .env file with your Calibre library path
python3 -m pip install .

或者直接从仓库安装：

python3 -m pip install git+https://github.com/ajtudela/calibre_mcp_server.git

使用

在紫外线（UV）下奔跑

uv run calibre_mcp_server

使用 pip 安装后运行

python3 -m calibre_mcp_server

HTTP 模式（适用于容器）

在容器化环境中以HTTP模式运行：

# Set environment variable
export TRANSPORT_MODE=http
export HTTP_HOST=0.0.0.0
export HTTP_PORT=9001

Claude Desktop/Cursor/VSCode 的配置示例

使用紫外线（推荐）

将此配置添加到您的应用程序设置（mcp.json）中：

{
  "calibre mcp server": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/calibre_mcp_server",
      "calibre_mcp_server"
    ],
    "env": {
        "CALIBRE_LIBRARY_PATH": "YOUR_CALIBRE_LIBRARY_PATH"
    }
  }
}

使用 pip 进行安装

{
  "calibre mcp server": {
    "type": "stdio",
    "command": "python3",
    "args": [
      "-m",
      "calibre_mcp_server"
    ],
    "env": {
        "CALIBRE_LIBRARY_PATH": "YOUR_CALIBRE_LIBRARY_PATH"
    }
  }
}

技术说明

  • 数据库连接自动连接管理，具备适当的错误处理功能
  • 配置验证启动验证确保所有必需设置均已存在
  • SQLite优化通过适当的索引和连接池实现高效查询
  • 搜索模式支持SQL LIKE通配符（%）以实现灵活的模式匹配
  • 只读访问安全、只读访问Calibre库数据库
  • 内存高效优化查询并妥善清理资源
  • 错误恢复优雅地处理数据库错误和网络问题

贡献；助力

  1. 为仓库创建分支
  2. 创建一个特性分支
  3. 按照既定模式进行修改
  4. 确保所有模块编译无误
  5. 根据需要更新文档
  6. 提交一个拉取请求

许可证

此项目遵循Apache 2.0许可证授权——详情请参阅LICENSE文件。

相关 MCP