zlib-mcp

A stdio MCP server that gives any AI agent tool — Claude Code, Codex CLI, Cursor, Claude Desktop — the ability to search z-library and download books.

Bring your own account. There is no shared backend, no API key, no proxy: the server runs on your machine, talks straight to z-library, and uses your credentials and your quota.

Tools

zlib_download only appears once you set ZLIB_DOWNLOAD_DIR — an MCP server that can write files anywhere by default is not an acceptable default, so you have to name the directory yourself.

Requirements

• Node.js ≥ 20

• A z-library account

Setup in 5 minutes

1. Get your credentials

If you already know your remix_userid / remix_userkey, skip ahead. Otherwise add the server with just your email and password (see the config snippets below), then ask your agent to run zlib_login once and put the returned remix_id / remix_key into the config permanently.

You can also run it straight from a terminal:

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

2. Add the server to your client

Every client takes the same three things: the command npx, the argument zlib-mcp, and an env block.

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

Or edit ~/.claude.json / .mcp.json directly using the JSON below.

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. Try it

Find me Kleppmann's Designing Data-Intensive Applications in epub, then download the first result.

Configuration

Credential precedence

1. ZLIB_REMIX_ID + ZLIB_REMIX_KEY

2. Cached credentials from a previous ZLIB_EMAIL login (~/.zlib-mcp/credentials.json, mode 600)

3. ZLIB_EMAIL + ZLIB_PASSWORD → logged in on first tool call, not at startup

The cache exists so a client restart does not trigger a fresh login every time — repeated logins are what makes z-library's anti-abuse system notice you. It stores only the remix id and key; your password is never written to disk, logged, or returned by any tool. On Windows the 600 mode is a no-op (the OS ignores POSIX permissions) — set ZLIB_CREDENTIAL_CACHE=0 if that matters to you.

If nothing is configured the server still starts and lists its tools; calling one returns instructions on what to set. It does not crash — a crashed MCP server just shows up as "unavailable" in most clients, with nothing to debug.

Troubleshooting

"Upstream host … appears to be blocking this request" — the mirror is behind an anti-bot wall. Set ZLIB_HOST to another one and restart the client. Known mirrors change often; 1lib.sk is currently blocked, pkuedu.xyz currently works. Anything that serves the same /eapi/* endpoints will do.

"z-library rejected the current credentials" — your remix key expired. Run zlib_login again and update the config. If you use the email/password fallback, delete ~/.zlib-mcp/credentials.json to force a fresh login.

"download quota reached" — free accounts get a small number of downloads per day. zlib_limits shows the counter; it resets on z-library's side at midnight UTC.

Nothing appears in the client — check the client's MCP log; this server writes all diagnostics to stderr. ZLIB_LOG_LEVEL=debug makes it chattier.

zlib_download is missing — you did not set ZLIB_DOWNLOAD_DIR. That is by design.

Development

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

To try an unreleased version straight from git, point your client's command/args at npx / ["-y", "github:shiyi-0x7f/zlib-mcp"] — the prepare script builds it on install.

Tests never hit the real upstream — fetch is stubbed everywhere.

Legal

This tool only provides API access to your own z-library account. It hosts nothing, distributes nothing, and ships no copyrighted content. Making sure your use of it is lawful where you are is on you. Your account, your quota, your risk — an account banned for abuse is yours to lose.

License

MIT