Calibre Librarian MCP

Calibre图书管理员MCP服务器


模型上下文协议（MCP）服务器，通过xmcp向Claude显示Calibre目录。

需求

• Node.js: v24.13.0 （如果使用，则自动管理 nvm use).
• pnpm：版本 10.28.0 或更新。
• Calibre CLI工具: calibredb 和 ebook-convert 必须安装在PATH上。
• 环境变量:

- CALIBRE_LIBRARY_PATH –Calibre库目录的绝对路径。 - CALIBRE_DB_COMMAND –位置 calibredb 可执行（例如。， /opt/homebrew/bin/calibredb). - FAVORITE_SEARCH_ENGINE_URL –服务器提供外部图书查找时使用的基本URL（默认为DuckDuckGo： https://duckduckgo.com/?q=).

设置

1. 克隆并进入仓库：

   git clone https://github.com/chepetime/calibre-librarian-mcp.git
   cd calibre-librarian-mcp

1. 使用pnpm安装依赖项：

   pnpm install

1. 复制示例环境文件并填写路径：

   cp .env.example .env

更新变量，以便服务器可以访问您的Calibre库。

环境变量仅用于本地开发。对于Claude Desktop，您需要在Claude Desktop设置中配置服务器。

本地开发工作流程

在本地迭代时使用这些脚本：

• pnpm run dev –通过stdio监视文件并为MCP服务器提供服务。
• pnpm run lint –类型检查和lints项目。
• pnpm test –运行一次完整的单元测试套件。
• pnpm test:watch –每当源文件发生更改时，都会重新运行测试。

为Claude桌面构建（无Docker）

当您希望Claude Desktop（或任何MCP客户端）直接运行编译后的服务器时，请遵循以下流程：

1. 这样构建项目 dist/stdio.js 存在：

   pnpm run build

1. （可选）在本地运行内置输出以进行快速烟雾测试：

   pnpm start  # equivalent to: node dist/stdio.js

1. 通过编辑配置Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json （或通过应用内UI）。集 command 到 node，包括绝对路径 dist/stdio.js 作为第一 args 输入并提供所需的环境变量：

{
  "globalShortcut": "",
  "mcpServers": {
    "calibre-librarian": {
      "command": "node",
      "args": ["/Users/you/path/to/calibre-librarian-mcp/dist/stdio.js"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/Calibre",
        "CALIBRE_DB_COMMAND": "/opt/homebrew/bin/calibredb",
        "FAVORITE_SEARCH_ENGINE_URL": "https://duckduckgo.com/?q="
      }
    }
  },
  "preferences": {
    "quickEntryShortcut": "off",
    "menuBarEnabled": false
  }
}

Claude Desktop重新加载后，它将列出 优秀图书管理员 每当启用MCP的对话开始时，作为可用的MCP服务器。

Docker部署

当您喜欢隔离环境时，请在预装了Calibre的容器中运行服务器。

快速开始

# Build the image
docker build -t calibre-librarian-mcp .

# Run with your Calibre library mounted
docker run -it \
  -v /path/to/your/calibre/library:/library:ro \
  -e CALIBRE_LIBRARY_PATH=/library \
  calibre-librarian-mcp

Docker Compose

1. 复制和自定义 docker-compose.yml.

1. 设置库路径并启动堆栈：

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

Claude桌面与Docker

要让Claude Desktop直接运行容器，请将其指向 docker run:

{
  "mcpServers": {
    "calibre-librarian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/calibre/library:/library:ro",
        "-e",
        "CALIBRE_LIBRARY_PATH=/library",
        "calibre-librarian-mcp"
      ]
    }
  }
}

注： 移除 :ro 从卷装载并添加 -e CALIBRE_ENABLE_WRITE_OPERATIONS=true 以启用写入操作。

工具目录和示例

安装MCP CLI

以下示例使用 mcp CLI由Anthropic发布。使用以下任何选项安装（或运行）它：

• 全局安装（如果您经常调用MCP工具，建议使用）：

  npm install -g @anthropic-ai/mcp-cli
  # now `mcp --help` should work

• 无需全局安装即可一次性执行：

  npx @anthropic-ai/mcp-cli --help
  # or
  pnpm dlx @anthropic-ai/mcp-cli --help

CLI使用情况

所有工具都可以从MCP检查器或CLI调用：

mcp call calibre-librarian  ''

提示（例如。， merge_duplicates, library_cleanup, search_library)使用伴随命令：

mcp prompt calibre-librarian library_cleanup '{"focus":"missing covers"}'

交换 library_cleanup 对于下面列出的任何提示，请进行替换 calibre-librarian 使用您在中配置的服务器名称 mcp.json.

库概述和元数据

搜索与发现

全文和内容访问

清理和复制工作台

智能维护食谱

元数据编辑和自定义列

需要 CALIBRE_ENABLE_WRITE_OPERATIONS=true

设置和配置工具

环境变量

资源

服务器公开这些MCP资源：

故障排除

“calibredb:找不到命令”

服务器找不到Calibre CLI工具。解决：

• macOS（自制）: brew install calibre 或设置 CALIBRE_DB_COMMAND=/Applications/calibre.app/Contents/MacOS/calibredb
• macOS（应用程序）: CALIBRE_DB_COMMAND=/Applications/calibre.app/Contents/MacOS/calibredb
• 视窗: CALIBRE_DB_COMMAND=C:\Program Files\Calibre2\calibredb.exe
• Linux：通过包管理器安装Calibre，通常会添加 calibredb 前往PATH

“库路径不存在”

验证您的 CALIBRE_LIBRARY_PATH:

# Check the path contains metadata.db
ls "$CALIBRE_LIBRARY_PATH/metadata.db"

“写入操作已禁用”

编写工具(set_metadata, set_custom_column, bulk_retag 随着 preview:false等等）要求：

CALIBRE_ENABLE_WRITE_OPERATIONS=true

将此添加到您的 .env 文件或Claude桌面配置。

“命令超时”

对于大型库，请增加超时时间：

CALIBRE_COMMAND_TIMEOUT_MS=60000  # 60 seconds

“全文搜索不返回结果”

必须启用Calibre FTS：

1. 打开口径
2. 首选 偏好→ 搜索
3. 启用 全文搜索
4. 点击 重新索引所有书籍

服务器未出现在Claude Desktop中

1. 验证配置文件路径：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 检查JSON语法是否有效

1. 完全重新启动克劳德桌面

1. 检查Claude Desktop日志是否有错误

MCP检验员测试

使用内置验证指南：

# Start dev server
npm run dev

# In another terminal, run inspector
npx @anthropic/mcp-inspector

或者使用 generate_claude_config 工具来获取您的配置。

许可证

麻省理工学院