zlib-mcp

一个基于 stdio 的 MCP 服务器，让任何 AI 代理工具——Claude Code、Codex CLI、Cursor、Claude Desktop——都能搜索 z-library 并下载书籍。

自带账户。 没有共享后端、没有 API 密钥、没有代理：服务器运行在你的机器上，直接与 z-library 通信，并使用你的凭证和你的配额。

工具

zlib_download 只有在你设置了 ZLIB_DOWNLOAD_DIR 后才会出现 —— 一个默认允许在任意位置写入文件的 MCP 服务器并不是可接受的默认行为，所以你必须自己指定目录。

要求

• Node.js ≥ 20

• 一个 z-library 账户

5 分钟完成设置

1. 获取你的凭证

如果你已经知道自己的 remix_userid / remix_userkey，请跳过后面的步骤。否则，先用你的邮箱和密码添加服务器（见下面的配置示例），然后让代理运行一次 zlib_login，并将返回的 remix_id / remix_key 永久写入配置。

你也可以直接从终端运行：

ZLIB_EMAIL=you@example.com ZLIB_PASSWORD='…' npx zlib-mcp

2. 将服务器添加到你的客户端

每个客户端都需要同样的三样东西：命令 npx、参数 zlib-mcp 和一个 env 块。

claude mcp add zlib \
  --env ZLIB_REMIX_ID=123456 \
  --env ZLIB_REMIX_KEY=your_remix_userkey \
  --env ZLIB_DOWNLOAD_DIR="$HOME/Downloads/books" \
  -- npx -y zlib-mcp

或者直接使用下面的 JSON 编辑 ~/.claude.json / .mcp.json。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zlib": {
      "command": "npx",
      "args": ["-y", "zlib-mcp"],
      "env": {
        "ZLIB_REMIX_ID": "123456",
        "ZLIB_REMIX_KEY": "your_remix_userkey",
        "ZLIB_DOWNLOAD_DIR": "/Users/you/Downloads/books"
      }
    }
  }
}

{
  "mcpServers": {
    "zlib": {
      "command": "npx",
      "args": ["-y", "zlib-mcp"],
      "env": {
        "ZLIB_REMIX_ID": "123456",
        "ZLIB_REMIX_KEY": "your_remix_userkey",
        "ZLIB_DOWNLOAD_DIR": "/Users/you/Downloads/books"
      }
    }
  }
}

[mcp_servers.zlib]
command = "npx"
args = ["-y", "zlib-mcp"]

[mcp_servers.zlib.env]
ZLIB_REMIX_ID = "123456"
ZLIB_REMIX_KEY = "your_remix_userkey"
ZLIB_DOWNLOAD_DIR = "/Users/you/Downloads/books"

3. 试试看

帮我找 Kleppmann 的 Designing Data-Intensive Applications 的 epub 格式，然后下载第一个结果。

配置

凭证优先级

1. ZLIB_REMIX_ID + ZLIB_REMIX_KEY

2. 之前使用 ZLIB_EMAIL 登录时缓存的凭证（~/.zlib-mcp/credentials.json，权限 600）

3. ZLIB_EMAIL + ZLIB_PASSWORD → 在首次调用工具时登录，而不是启动时

缓存的存在是为了避免每次客户端重启都触发重新登录——反复登录正是让 z-library 的反滥用系统注意到你的原因。它只存储 remix id 和 key；你的密码永远不会被写入磁盘、记录日志，也不会被任何工具返回。在 Windows 上，600 权限模式是无效操作（操作系统会忽略 POSIX 权限）——如果这对你很重要，请设置 ZLIB_CREDENTIAL_CACHE=0。

如果什么都没配置，服务器仍会启动并列出其工具；调用某个工具会返回需要设置什么的说明。它不会崩溃——崩溃的 MCP 服务器在大多数客户端中只会显示为“不可用”，没有任何可供调试的内容。

故障排查

“上游主机……似乎正在屏蔽此请求” —— 该镜像启用了反机器人防护。将 ZLIB_HOST 改为其他镜像并重启客户端。已知镜像经常更换；1lib.sk 目前已被屏蔽，pkuedu.xyz 目前可用。任何提供相同 /eapi/* 端点的镜像都可以。

“z-library 拒绝了当前凭证” —— 你的 remix key 已过期。重新运行 zlib_login 并更新配置。如果使用邮箱/密码备用方式，请删除 ~/.zlib-mcp/credentials.json 以强制重新登录。

“下载配额已达上限” —— 免费账户每天只有少量下载次数。zlib_limits 会显示计数器；它会在 UTC 午夜时在 z-library 侧重置。

客户端中不显示任何内容 —— 请检查客户端的 MCP 日志；此服务器将所有诊断信息写入 stderr。ZLIB_LOG_LEVEL=debug 会输出更多日志。

缺少 zlib_download —— 你没有设置 ZLIB_DOWNLOAD_DIR。这是有意为之。

开发

pnpm install
pnpm check      # format check → lint → typecheck → tests
pnpm build

如果想直接从 git 试用未发布版本，请将客户端的 command/args 指向 npx / ["-y", "github:shiyi-0x7f/zlib-mcp"] —— prepare 脚本会在安装时构建。

测试永远不会访问真实上游——fetch 在所有地方都被打桩了。

法律声明

此工具仅提供对你自己的 z-library 账户的 API 访问。它不托管任何内容、不分发任何内容，也不附带任何受版权保护的内容。确保你在所在地区的使用合法是你的责任。你的账户、你的配额、你的风险——因滥用而被封禁的账户，损失由你自己承担。

许可证

MIT