ni-c/calibreweb-mcp

A read-only Model Context Protocol (MCP) server for
Calibre-Web (and
Calibre-Web Automated),
the self-hosted ebook library web UI.
Lets MCP clients like Claude Code, Claude Desktop or Codex search your library,
browse the curated views and shelves, follow per-format download links and pull cover
images straight into the conversation. It never writes anything: every tool is a GET.
Six tools is the ceiling, not the floor: CALIBRE_WEB_ALLOW_TOOLS=essential
registers a curated five instead, and a model picks the right tool far more
reliably from five than from six — see
choosing which tools load.
Calibre-Web has no REST API — its only stable machine-readable interface is the OPDS
catalog feed it serves for e-reader apps. This server speaks that feed: Atom XML with
HTTP Basic auth in, structured book data out.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query. -->
What makes it different
**The API Calibre-Web never had.** Calibre-Web exposes no REST API — its only
stable machine interface is the OPDS Atom feed built for e-reader apps. These
tools parse that feed into structured book data with numeric ids, per-format
download URLs and bounded summaries.
**Read-only by construction.** All six tools are GETs. Redirects are refused so
Basic credentials never travel, XML carrying a DOCTYPE is rejected outright,
hrefs are locked to the configured origin, and metadata is marked as the
untrusted data it is.
Requirements
- Node.js 22 or newer
- A Calibre-Web instance (developed against the current
linuxserver/calibre-web image; Calibre-Web Automated works the same way)
- A Calibre-Web user for the server. The OPDS feed authenticates with the
normal web login — use a **dedicated account with only the View and Download
roles**, not your admin account. If the instance allows anonymous browsing,
the server can also run without credentials.
Configuration
| Variable | Required | Description |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| CALIBRE_WEB_URL | yes | Root URL of the instance, e.g. https://books.example.com. The /opds path is appended automatically. |
| CALIBRE_WEB_USERNAME | yes¹ | Username of the Calibre-Web account. |
| CALIBRE_WEB_PASSWORD | yes¹ | Password of that account (the web login password). |
| CALIBRE_WEB_INSECURE_TLS | no | true to accept self-signed certificates — scoped to the configured host only. |
| CALIBRE_WEB_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |
| CALIBRE_WEB_DENY_TOOLS | no | Same syntax; removed from whatever CALIBRE_WEB_ALLOW_TOOLS left |
¹ Leave **both** unset for an instance that allows anonymous browsing; setting
only one of them is a configuration error.
Choosing which tools load
CALIBRE_WEB_ALLOW_TOOLS and CALIBRE_WEB_DENY_TOOLS take comma-separated tool names;
a trailing * matches a whole family. essential is a curated preset of
five: search_books, list_books, list_shelves, get_shelf_books, get_stats.
An entry that matches no tool aborts startup and names it, so a typo cannot
silently hide a tool — an absent tool is not something anyone traces back to an
environment variable. A filtered tool is never registered, so it is absent from
tools/list and unknown to tools/call alike.
If you run several of these servers at once, mcp-hub
is the other answer — its /hub endpoint replaces every server's tools with six