# 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](https://github.com/onurhanak/libgen-api-enhanced) for LibGen / Library Genesis search and download metadata.
- [sertraline/zlibrary](https://github.com/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

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

Copy the environment example and fill local values:

```bash
cp .env.example .env
```

Important settings:

```bash
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:

```bash
./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:

```text
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:

```text
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:

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

If `library_dir` is omitted, the server uses `DOWNLOAD_BOOKS_LIBRARY_DIR`.

Default output layout:

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

## CLI

Search clean candidates:

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

Download a selected result:

```bash
uv run download-books download <ID>
```

Local diagnostic output:

```bash
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

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