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와 키만 저장됩니다. 비밀번호는 절대 디스크에 기록되지 않으며, 로그에 남지 않고, 어떤 도구로도 반환되지 않습니다. Windows에서 600 모드는 아무 효과가 없습니다(OS가 POSIX 권한을 무시함). 이 점이 중요하다면 ZLIB_CREDENTIAL_CACHE=0을 설정하세요.

아무것도 설정하지 않아도 서버는 시작되고 도구 목록을 표시합니다. 도구를 호출하면 설정해야 할 내용에 대한 안내가 반환됩니다. 서버는 충돌하지 않습니다. 충돌한 MCP 서버는 대부분의 클라이언트에서 "unavailable"로만 표시되어 디버깅할 것이 없습니다.

문제 해결

"Upstream host … appears to be blocking this request" — 미러가 안티봇 벽 뒤에 있습니다. ZLIB_HOST를 다른 것으로 설정하고 클라이언트를 재시작하세요. 알려진 미러는 자주 바뀝니다. 1lib.sk는 현재 차단되어 있고, pkuedu.xyz는 현재 작동합니다. 동일한 /eapi/* 엔드포인트를 제공하는 어떤 것이든 됩니다.

"z-library rejected the current credentials" — remix 키가 만료되었습니다. zlib_login을 다시 실행하고 설정을 업데이트하세요. 이메일/비밀번호 대체 방식을 사용한다면 ~/.zlib-mcp/credentials.json을 삭제하여 새 로그인을 강제하세요.

"download quota reached" — 무료 계정은 하루에 소량의 다운로드만 가능합니다. zlib_limits가 카운터를 표시합니다. z-library 측에서 UTC 기준 자정에 초기화됩니다.

클라이언트에 아무것도 표시되지 않음 — 클라이언트의 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