内容
# Z-Library MCP 服务器
[](https://github.com/loganrooks/zlibrary-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/zlibrary-mcp)
[](https://github.com/loganrooks/zlibrary-mcp/blob/master/LICENSE)
一个模型上下文协议（MCP）服务器，为 AI 助手（如 Claude Code、Claude Desktop、RooCode、Cline）提供搜索 Z-Library、下载书籍和提取文档内容的功能，用于检索增强生成（RAG）工作流。该服务器使用 Node.js/TypeScript MCP 前端和 Python 桥接后端进行文档处理。
关于本项目的目的和功能，请参见 [VISION.md](VISION.md)。
## 快速入门
**先决条件：** Node.js 22+，Python 3.10+，以及 [UV](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh`）
```bash
npm install -g zlibrary-mcp
cd "$(npm root -g)/zlibrary-mcp" && bash setup-uv.sh # 一次性 Python 环境设置
```
然后将以下内容添加到您的 MCP 客户端配置中（Claude Code `.mcp.json`，Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"zlibrary": {
"command": "zlibrary-mcp",
"env": {
"ZLIBRARY_EMAIL": "your-email@example.com",
"ZLIBRARY_PASSWORD": "your-password"
}
}
}
}
```
如果您正在开发或贡献，请安装[源代码](#选项-二-从源代码进行开发)而不是此选项。
## 架构概述
```mermaid
flowchart LR
subgraph "MCP 客户端"
A[Claude Desktop / Claude Code / RooCode]
end
subgraph "stdio 传输"
B[Node.js MCP 服务器<br/>src/index.ts]
end
subgraph "HTTP 传输"
SG[SuperGateway :8000]
end
subgraph "Python 桥接"
C[python_bridge.py]
D[lib/rag/ 模块]
end
subgraph "外部"
E[Z-Library EAPI]
end
A -->|stdio| B
A -->|SSE/HTTP| SG -->|stdio| B
B -->|PythonShell| C
C --> D
C -->|httpx| E
```
- **Node.js/TypeScript MCP 服务器**：通过 McpServer `server.tool()` API 注册了 13 种工具（MCP SDK 1.25+）
- **Python 桥接**：Z-Library EAPI 客户端（httpx）+ 文档处理（lib/rag/ 模块）
- **EAPI 传输**：`/eapi/` 上的 JSON API 端点，绕过 Cloudflare 浏览器挑战
- **基于 UV 的 Python 环境**：项目本地 `.venv/`，使用 `uv.lock` 进行可复制构建
- **Z-Library 分叉**：用于搜索和文件下载的自定义 EAPI 客户端
- **RAG 管道**：EPUB/PDF/TXT 提取，具有质量检测，输出到文件（非内存）
## 可用的 MCP 工具（共 13 个）
### 搜索工具（7 个）
| 工具 | 描述 |
|------|-------------|
| `search_books` | 基于关键词的基本搜索，带有过滤器 |
| `full_text_search` | 在书籍内容中搜索 |
| `search_by_term` | 通过术语进行概念导航 |
| `search_by_author` | 高级作者搜索 |
| `search_advanced` | 模糊匹配检测，带有单独的精确/模糊结果 |
| `search_multi_source` | 跨多个来源的并行搜索 |
| `get_recent_books` | 最近添加的书籍 |
### 元数据工具（1 个）
| 工具 | 描述 |
|------|-------------|
| `get_book_metadata` | 完整的元数据提取（术语，描述，评分） |
### 收藏工具（1 个）
| 工具 | 描述 |
|------|-------------|
| `fetch_booklist` | 精选收藏内容 |
### 下载和处理工具（2 个）
| 工具 | 描述 |
|------|-------------|
| `download_book_to_file` | 可选的文件基 RAG 包输出下载 |
| `process_document_for_rag` | 从 EPUB/PDF/TXT 中提取文件基 RAG 包 |
### 实用工具（2 个）
| 工具 | 描述 |
|------|-------------|
| `get_download_limits` | 检查每日下载配额 |
| `get_download_history` | 查看最近的下载记录 |
有关完整的参数文档、类型和示例，请参见 [API 参考](docs/api.md)。
## 安装
### 选项 A：npm（推荐）
**先决条件：** Node.js 22+，Python 3.10+，[UV](https://docs.astral.sh/uv/)
```bash
npm install -g zlibrary-mcp
```
然后在已安装的包内设置 Python 环境（一次性）：
```bash
cd "$(npm root -g)/zlibrary-mcp"
curl -LsSf https://astral.sh/uv/install.sh | sh # 如果需要，安装 UV
bash setup-uv.sh
```
该包自带完整的 Python 桥接器（`lib/`，`zlibrary/` 分叉，`pyproject.toml`，`uv.lock`），因此无需克隆。自 v1.3.0 起，发布工作流验证标签与 `package.json` 并发布具有溯源信息，因此注册表版本跟踪 GitHub 发布；如果 `npm view zlibrary-mcp version` 曾经落后于 [最新发布](https://github.com/loganrooks/zlibrary-mcp/releases)，则是一个值得报告的发布管道错误。
### 选项 B：从源代码（用于开发）
**先决条件：** Node.js 22+，Python 3.10+，[UV](https://docs.astral.sh/uv/)
```bash
# 1. 安装 UV（一次性，如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. 克隆和构建
git clone https://github.com/loganrooks/zlibrary-mcp.git
cd zlibrary-mcp
git lfs pull # 填充 LFS 跟踪的测试 PDF（不要运行 `git lfs install`；
# 它与存储库的 Husky 管理的钩子冲突）
bash setup-uv.sh # 创建 .venv/ 并安装 Python 依赖项
npm install # 安装 Node.js 依赖项
npm run build # 将 TypeScript 编译到 dist/
```
**MCP 客户端配置（stdio 传输）：**
Claude Code（项目根目录中的 `.mcp.json`）：
```json
{
"mcpServers": {
"zlibrary": {
"command": "node",
"args": ["/绝对路径/to/zlibrary-mcp/dist/index.js"],
"env": {
"ZLIBRARY_EMAIL": "your-email@example.com",
"ZLIBRARY_PASSWORD": "your-password"
}
}
}
}
```
RooCode / Cline（`mcp_settings.json`）：
```json
{
"mcpServers": {
"zlibrary-local": {
"command": "node",
"args": ["/绝对路径/to/zlibrary-mcp/dist/index.js"],
"env": {
"ZLIBRARY_EMAIL": "your-email@example.com",
"ZLIBRARY_PASSWORD": "your-password"
},
"transport": "stdio",
"enabled": true
}
}
}
```
### 选项 C：Docker（HTTP 传输）
**先决条件：** Docker
版本化的镜像在每次发布时发布到 GHCR（`latest`，`1.3`，`1.3.2`，...），无需克隆或构建：
```bash
docker run -d --name zlibrary-mcp -p 8000:8000 \
-e ZLIBRARY_EMAIL="your-email@example.com" \
-e ZLIBRARY_PASSWORD="your-password" \
-v "$PWD/downloads:/app/downloads" \
ghcr.io/loganrooks/zlibrary-mcp:latest
```
镜像包装了 stdio 服务器的 [SuperGateway](https://github.com/supercorp-ai/supergateway)，通过 SSE 在 `http://localhost:8000/sse` 暴露 MCP。验证它是否正在提供服务：
```bash
curl -s -N --max-time 3 http://localhost:8000/sse | head -2
# event: endpoint
# data: /message?sessionId=...
```
> Alpine 注意：OpenCV 没有 musl 轮，因此在容器中无法使用 X 标记检测；
> 其他功能都正常工作。
**从源代码构建**（使用 compose 添加 `/health` 端点）：
```bash
git clone https://github.com/loganrooks/zlibrary-mcp.git && cd zlibrary-mcp
cp docker/env.example docker/.env # 然后编辑您的凭证
docker compose -f docker/docker-compose.yaml up -d
curl http://localhost:8000/health
```
**MCP 客户端配置（SSE/HTTP 传输）：**
```json
{
"mcpServers": {
"zlibrary": {
"command": "npx",
"args": ["-y", "supergateway", "--sse", "http://localhost:8000/sse"]
}
}
}
```
## 输出格式（RAG 处理）
RAG 管道将下载的文档（EPUB，PDF，TXT）处理成干净的文本文件，用于检索增强生成工作流。
- **输出位置：** 处理后的文本文件保存在 `./processed_rag_output/`
- **基于文件的输出：** 工具返回文件路径而不是原始文本内容，避免 AI 助手中的上下文溢出
- **包契约：** `processed_file_path` 保持正文锚点，具有附加的兄弟字段，如 `metadata_file_path`，可选的 `footnotes_file_path` 和可用的 `output_files` 映射
- **支持的格式：** EPUB，PDF 和 TXT
- **质量检测：** 管道自动检测文档质量（OCR 与数字文本）并应用适当的提取策略
- **学术格式：** 在可能的情况下保留脚注、章节结构和学术格式
使用 `download_book_to_file` 和 `process_for_rag: true` 进行组合下载和处理，或使用 `process_document_for_rag` 处理现有文件。
## 配置
服务器需要 Z-Library 凭证，设置为环境变量：
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `ZLIBRARY_EMAIL` | 是 | Z-Library 账户电子邮件 |
| `ZLIBRARY_PASSWORD` | 是 | Z-Library 账户密码 |
| `ZLIBRARY_MIRROR` | 否 | 自定义 Z-Library 镜像 URL |
服务器在启动时验证凭证，如果凭证丢失，则会发出明确的错误。
### 日志记录
诊断信息输出到 **stderr**，而非 stdout：在 stdio 传输中，stdout 是 JSON-RPC 通道，写入其他内容会破坏协议流，导致客户端断开连接。您的 MCP 客户端会将 stderr 捕获到其自己的日志中。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | `silent`，`error`，`warn`，`info` 或 `debug` |
`debug` 添加每个请求的论点跟踪，**包括您的搜索查询**。在附加到错误报告之前，请清理客户端日志。
### 诊断问题
```bash
npm run doctor
```
此命令直接探测 Z-Library、Anna's Archive 和 LibGen，并报告哪些服务可用。那些未记录的第三方服务会更改域名而没有通知，因此来自 MCP 客户端的上游中断和此服务器中的错误看起来相同。在报告问题之前，请运行此命令 - 并参阅 [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) 获取与设置相关的服务器立即退出原因。
### 重试和熔断器
所有 API 操作都包含具有指数退避和熔断器保护的自动重试。这些可以通过环境变量配置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `RETRY_MAX_RETRIES` | `3` | 最大重试次数 |
| `RETRY_INITIAL_DELAY` | `1000` | 初始重试延迟（毫秒） |
| `RETRY_MAX_DELAY` | `30000` | 最大重试延迟（毫秒） |
| `RETRY_FACTOR` | `2` | 指数退避乘数 |
| `CIRCUIT_BREAKER_THRESHOLD` | `5` | 断路器打开前的失败次数 |
| `CIRCUIT_BREAKER_TIMEOUT` | `60000` | 断路器打开后重试前的等待时间（毫秒） |
详见 [docs/RETRY_CONFIGURATION.md](docs/RETRY_CONFIGURATION.md)。
## 开发
### 运行测试
```bash
# Node.js 测试（仅限 Jest -- npm test 不运行 pytest）
npm test
# Python 测试 -- 快速套件（常规命令）
uv run pytest -m "not slow and not integration and not performance"
# Python 测试 -- 完整语料库（需要 LFS 水合测试 PDF）
uv run pytest
# 特定 Python 测试
uv run pytest __tests__/python/test_rag_processing.py
```
### 构建
```bash
npm run build
```
## 常见问题
### 为什么使用 EAPI 而不是 HTML 抓取？
Z-Library 部署了 Cloudflare 浏览器挑战（2026 年 1 月），阻止所有自动化客户端的 HTML 页面请求。`/eapi/` 上的 EAPI JSON 端点不受这些挑战的影响，为程序化访问提供了可靠的访问方式。参见 `docs/adr/ADR-005-EAPI-Migration.md`。
### 为什么在 .mcp.json 中使用 `node` 而不是 `uv`？
MCP 服务器是 Node.js 应用程序。UV 仅在设置期间使用（`uv sync`）以创建 `.venv/` 并安装 Python 依赖项。在运行时，Node.js 运行 MCP 服务器，该服务器内部调用 `.venv/bin/python`。
```
设置： uv sync --> 创建 .venv/
构建： npm run build --> 将 TypeScript 编译到 dist/
运行时： node dist/index.js --> 运行 MCP 服务器 --> 内部调用 .venv/bin/python
```
### 如果我移动项目目录怎么办？
没问题。`.venv/` 随着项目移动（UV 创建项目本地环境）。
## 贡献
欢迎贡献！有关设置说明、代码风格、测试和 PR 工作流程，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参见 LICENSE 文件。
## 免责声明
本工具仅用于教育和研究目的。用户负责遵守下载和使用受版权保护材料的法律法规。访问 Z-Library 在某些司法管辖区可能受到限制。
