Calibre-Web

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.

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 24 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

¹ 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.

CALIBRE_WEB_ALLOW_TOOLS=essential

CALIBRE_WEB_ALLOW_TOOLS=search_books,list_shelves CALIBRE_WEB_DENY_TOOLS=get_cover

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 meta-tools.

Installation

Claude Code

claude mcp add calibreweb \

-e CALIBRE_WEB_URL=https://books.example.com \ -e CALIBRE_WEB_USERNAME=reader \ -e CALIBRE_WEB_PASSWORD=... \ -- npx calibreweb-mcp

Claude Desktop

{

"mcpServers": { "calibreweb": { "command": "npx", "args": ["calibreweb-mcp"], "env": { "CALIBRE_WEB_URL": "https://books.example.com", "CALIBRE_WEB_USERNAME": "reader", "CALIBRE_WEB_PASSWORD": "..." } } } }

Codex

[mcp_servers.calibreweb]

command = "npx" args = ["calibreweb-mcp"] env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }

Docker

docker run -i --rm \

-e CALIBRE_WEB_URL=https://books.example.com \ -e CALIBRE_WEB_USERNAME=reader \ -e CALIBRE_WEB_PASSWORD=... \ ghcr.io/ni-c/calibreweb-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches calibreweb-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "calibreweb": { "command": "npx", "args": ["-y", "calibreweb-mcp"], "env": { "CALIBRE_WEB_ALLOW_TOOLS": "essential" }, "denyTools": ["get_cover"] } } }

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

All tools are read-only (readOnlyHint: true).

Book entries include authors, tags, series (with index), rating, a bounded summary, a cover URL and per-format download URLs — ready-made links a human can open, since the model itself has no reason to download an EPUB.

Structured output

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose:

{

"untrusted": true, "source": "calibre-web", "totalFound": 2, "truncated": false, "books": [{ "id": 7, "title": "Dune", "authors": ["Frank Herbert"] }], "notes": ["Book titles, authors, tags, series and summaries come from …"], }

The untrusted marker is a field and not only a line in notes, because a client that reads the structured half would otherwise have to find the warning in a list of sentences. The two tools without it are get_stats, which is four counters this server has checked are numbers, and get_cover, which reports an id, a media type from a four-entry allowlist and a byte count — the image itself stays in the content block where a client renders it.

An over-budget result drops book summaries as before. Where that is still not enough it is now an error rather than JSON cut at the ceiling: unparseable text was tolerable in a text block and is not something structuredContent can carry, and the two channels have to hold the same value.

Pagination

Feeds are paginated by the instance's _books per page_ setting (default 60); the page size is not