NeverTooManyBooks can talk directly to a Calibre Content Server (CCS) — the built-in HTTP server included with the free, open-source Calibre desktop application. Once the connection is configured you can pull books from your Calibre libraries into NTMB, push books back from NTMB to Calibre, and keep metadata like reading progress in sync across both apps. This is not a cloud service: the sync happens over a direct HTTP connection between your Android device and the machine running Calibre, so your data never passes through a third-party server.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tfonteyn/NeverTooManyBooks/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before starting setup, make sure you have:- Calibre installed on a desktop or server machine (Windows, macOS, or Linux).
- The Content Server enabled in Calibre — see Step 1 below.
- Your Android device and the Calibre machine on the same local network (or port-forwarding configured for remote access).
By default the Content Server is only reachable on your local network. If you need to sync while away from home, you must either set up port-forwarding on your router or use a VPN to reach your local network. Exposing the Content Server to the public internet without authentication is not recommended.
Setup
Enable the Content Server in Calibre
Open Calibre on your desktop. Go to Preferences → Sharing → Sharing over the network. Check Enable Content Server and note the port (default 8080). Click Apply.Find your machine’s local IP address (e.g.
192.168.1.10) using your OS network settings. The full server URL will be something like http://192.168.1.10:8080.Optionally, set a username and password in the same Calibre preference pane under Require username and password.Open Calibre settings in NeverTooManyBooks
On your Android device, open NeverTooManyBooks and go to Settings → Calibre. Tap Enable Calibre sync to turn the feature on.
Enter the server URL
Tap Website address and type the full URL of your Content Server, for example:If your server uses HTTPS with a self-signed certificate, you can import that certificate from a file in the same settings screen so the app trusts it.
Enter credentials (if required)
If you set a username and password in Calibre, enter them in the Username and Password fields. NeverTooManyBooks supports both HTTP Basic and HTTP Digest authentication automatically.
Test the connection
Tap Test connection. The app will attempt to reach the server and retrieve metadata. A green confirmation message means the server is reachable and the credentials are accepted. If the test fails, double-check the URL, ensure the Content Server is running, and verify that no firewall is blocking port 8080.
Map Calibre libraries to bookshelves
Go to Settings → Calibre → Library mapping (or tap the Library map button on the Calibre sync screen). Each Calibre library you have will appear in a list. Assign each library to a NeverTooManyBooks bookshelf — books imported from that library will land on the matched bookshelf, and books exported from that bookshelf will go to the paired Calibre library.
Running a Sync
Once set up, you can start a sync from the Calibre sync screen, reachable via the main navigation menu.- Import from Calibre
- Export to Calibre
- Virtual Libraries
Tap Import to pull books from Calibre into NeverTooManyBooks. You can choose to import:
- New books only — books in Calibre that don’t yet exist in NTMB.
- Updated books — books whose Calibre metadata has changed since the last sync date.
- Both new and updated — the most complete option.
Custom Fields
Calibre supports user-defined custom columns (prefixed with#). NeverTooManyBooks can read and write these fields when they are configured in Settings → Calibre → Custom fields. Common mappings include:
| Calibre custom field | NTMB field |
|---|---|
#read | Read status (boolean) |
#read_start | Date started reading |
#read_end | Date finished reading |
#date_read | Date finished reading (alternative name) |
#read_progress | Reading progress (percentage or page count) |
#rating | Star rating |
#notes | Personal notes |
#read_progress field receives special handling: its value is parsed from a percentage string (e.g. "42%"), a page/total fraction (e.g. "100 / 332"), or a decimal fraction (e.g. "0.42").
SSL / HTTPS and Certificates
If your Calibre Content Server is configured with HTTPS (recommended for remote access), you can:- Use a certificate from a trusted CA — the app will accept it automatically.
- Import a self-signed certificate from a
.crtor.pemfile via Settings → Calibre → Import CA certificate. This adds it to the app’s trusted store without affecting system-wide certificate trust.
Troubleshooting
Connection test fails immediately
Connection test fails immediately
Check that the Calibre Content Server is running (the Calibre taskbar icon should show the server as active) and that the URL includes the correct port. Try opening the URL in a browser on the same device to rule out network issues.
Authentication errors (401 / 403)
Authentication errors (401 / 403)
Re-enter your credentials in Settings → Calibre. If you recently changed the password in Calibre, update it here too. Make sure there are no leading or trailing spaces in the username or password fields.
Books import but have no covers
Books import but have no covers
Calibre serves covers via a separate endpoint. Ensure the Content Server has permission to serve book content (check Calibre Preferences → Sharing → Sharing over the network → Require username and password for accessing book content) and that the download folder in NTMB has write permission.
Virtual libraries are not showing
Virtual libraries are not showing
Virtual library support requires the companion NTMB plugin to be installed in Calibre. Without it, the app can still import and export books but virtual library data will not be available.