How to Use KOReader with BookShelves via OPDS

You have books in BookShelves on your Mac. You want to read them on your Kindle, Kobo, or PocketBook running KOReader. Normally that means cables, file managers, or emailing files to yourself.

There’s a faster way: BookShelves has a built-in OPDS server that lets KOReader browse and download your entire library over Wi-Fi. No cables. No file transfers. No cloud services.

What You Need

• BookShelves on your Mac (the OPDS server is macOS-only)
• KOReader installed on your e-reader (Kindle, Kobo, PocketBook, or Android)
• Both devices on the same Wi-Fi network

Step 1: Enable the OPDS Server in BookShelves

1. Open BookShelves on your Mac
2. Go to Settings > Advanced
3. Find the Web Server section and enable it
4. Note the URL shown (something like http://192.168.1.100:8080)

That’s your OPDS server running. Any device on your local network can now browse your library.

BookShelves also advertises itself via Bonjour (mDNS) on your local network. KOReader and other OPDS clients that support Bonjour can discover the server automatically — no need to type the URL manually.

Tip: If the URL shows localhost instead of an IP address, make sure your Mac is connected to Wi-Fi, not just Ethernet. The server binds to all network interfaces but displays the Wi-Fi address for device access.

Step 2: Add BookShelves as an OPDS Catalog in KOReader

1. On your KOReader device, tap the magnifying glass icon in the top toolbar
2. Select OPDS catalog
3. Tap the + (plus) icon at the top left
4. Enter the following:
   • Catalog name: BookShelves (or whatever you prefer)
   • Catalog URL: http://YOUR-MAC-IP:8080/opds (use the IP from Step 1)

Important: Include the /opds path at the end of the URL. Without it, KOReader will load the HTML web page instead of the OPDS feed.

Step 3: Browse and Download Books

1. In KOReader’s OPDS catalog list, tap BookShelves
2. You’ll see your library organized into:
   • All Books — your complete library, paginated (50 books per page)
   • Recent Books — books added in the last 30 days
   • Favorites — books you’ve marked as favorites in BookShelves
3. Tap any book to see its details, then tap Download to save it to your device

That’s it. The book downloads over Wi-Fi directly to your KOReader device.

Searching Your Library

KOReader’s OPDS browser supports search. When browsing the BookShelves catalog, use the search function to find books by title or author. The search requires at least two characters and matches against both fields.

What Formats Work?

BookShelves automatically converts MOBI, AZW, AZW3, and PRC files to EPUB during import. That means your OPDS catalog serves EPUB, PDF, and CBZ/CBR files — all of which KOReader handles natively. No format compatibility issues to worry about.

Even if you originally imported a Kindle-format book, KOReader receives a clean EPUB over OPDS.

Troubleshooting

KOReader Can’t Connect

• Check the IP address. Open BookShelves Settings and verify the displayed URL. Your Mac’s IP may change if your router assigns addresses dynamically.
• Same network? Your e-reader and Mac must be on the same Wi-Fi network. Some routers isolate devices on guest networks.
• Firewall blocking? macOS may block incoming connections. Go to System Settings > Network > Firewall and make sure BookShelves is allowed, or add port 8080 to the allowed list.
• Trailing slash. Some KOReader versions need http://192.168.1.100:8080/opds/ with a trailing slash. Try adding one if connection fails.

No Books Showing Up

• Make sure your BookShelves library has books in it. The OPDS server serves your actual library — it doesn’t pull from external sources.
• If you just imported books, give BookShelves a moment to process them before refreshing the catalog in KOReader.

Covers Not Loading

Book covers are served separately. On slower networks or older e-readers, covers may take a few seconds to appear. This is normal — the books themselves will still download fine.

Why OPDS?

OPDS (Open Publication Distribution System) is an open standard for distributing ebooks. Think of it like an RSS feed for books — any compatible reader can connect to any compatible server. It means:

• No vendor lock-in. Your books aren’t trapped in one ecosystem.
• Local network only. Nothing goes through the cloud. Your library stays private.
• Works with any OPDS client. Not just KOReader — Calibre, Thorium Reader, Aldiko, and many others support OPDS catalogs.

What Is KOReader?

KOReader is a free, open-source ebook reader that runs on Kindle, Kobo, PocketBook, and Android devices. It replaces the stock reading software with a feature-rich alternative that supports EPUB, PDF, MOBI, DjVu, and dozens of other formats. Key features include:

• OPDS catalog browser — connect to any OPDS server and download books over Wi-Fi
• Advanced typography — font selection, line spacing, margins, hyphenation
• Dictionary lookup — tap any word to look it up (supports StarDict and other formats)
• Progress sync — sync reading position across devices via a self-hosted server
• Battery efficiency — designed for e-ink displays with minimal battery drain

KOReader is especially popular with readers who want more control over their reading experience than the stock Kindle or Kobo software provides.

Beyond KOReader

The BookShelves OPDS server works with any OPDS-compatible app or device. If you use a different reader that supports OPDS, the setup is similar — just point it to http://YOUR-MAC-IP:8080/opds and browse your library.

For a full list of compatible apps, see the OPDS website. BookShelves supports both OPDS 1.2 (Atom/XML) and OPDS 2.0 (JSON), so it works with both older and newer clients.