download-books-mcp

Local MCP server and Codex skill for agent-driven book search and download through LibGen and Z-Library / Zeta Library.

This repo wraps two existing Python clients:

• onurhanak/libgen-api-enhanced for LibGen / Library Genesis search and download metadata.
• sertraline/zlibrary for Z-Library / Zeta Library search and authenticated downloads.

The purpose is to make those sources usable from MCP clients such as Codex, Claude Code, and other agents while keeping provider-specific details out of the agent-facing tool contract. The README is explicit for humans and GitHub search; the MCP tools and skill use neutral provider labels and clean IDs.

The MCP surface is intentionally small:

• search_books(...) returns clean candidates with a temporary id.
• download_book(id=...) downloads the selected candidate into a local library folder.

Internally, the server can query LibGen, Z-Library / Zeta Library, or both. Externally, provider internals stay behind neutral labels (provider_1, provider_2, all) so agents can use the MCP tools without handling provider-specific links, hashes, mirrors, URLs, or identifiers.

Use only sources, credentials, and documents you are authorized to access.

Install

git clone https://github.com/mateogon/download-books-mcp.git
cd download-books-mcp
uv sync

Copy the environment example and fill local values:

cp .env.example .env

Important settings:

DOWNLOAD_BOOKS_PROVIDER=all
DOWNLOAD_BOOKS_LIBRARY_DIR=~/Downloads/books
BOOK_PROVIDER_2_EMAIL=
BOOK_PROVIDER_2_PASSWORD=

Agent Installation

There are two pieces:

• MCP server: the runtime tools agents call.
• Skill: the workflow that tells Codex how to use those tools cleanly.

Add the MCP server to Codex by copying examples/codex-config.toml into ~/.codex/config.toml and replacing /absolute/path/to/download-books-mcp with your clone path.

Install the Codex skill:

./scripts/install-codex-skill.sh

Restart Codex after changing MCP config or installing the skill.

For Hermes, use examples/hermes-mcp.yaml.

MCP Tools

search_books

Parameters:

query: str
limit: int = 10
preferred_language: str = "English"
provider_name: str = "default"  # default | all | provider_1 | provider_2
search_type: str = "default"    # default | title | author
topic: str = "books"
preferred_author: str | None = None

Clean results include:

id, title, author, year, language, extension, size, publisher, pages, score

Raw provider internals are cached locally for download_book, but they are not returned in normal MCP results.

download_book

Parameters:

id: str | int
library_dir: str | None = None

If library_dir is omitted, the server uses DOWNLOAD_BOOKS_LIBRARY_DIR.

Default output layout:

<library_dir>/Sources/<Author - Title>/00 - Fuentes/<Title>.<extension>

CLI

Search clean candidates:

uv run download-books search "The Embodied Mind" --search-type title --limit 10

Download a selected result:

uv run download-books download <ID>

Local diagnostic output:

uv run download-books search "The Embodied Mind" --raw --json

Provider Routing

Visible provider options are:

• default uses DOWNLOAD_BOOKS_PROVIDER, defaulting to all
• all searches every available configured provider
• provider_1 searches only the LibGen adapter
• provider_2 searches only the Z-Library / Zeta Library adapter

Agents should normally leave provider routing at default.

The MCP and skill intentionally keep the neutral names. Humans reading this repo should understand the mapping; agents using the tool should not need to.

Development

uv run --extra dev pytest
uv run python -m compileall src