calibreweb-mcp

A read-only Model Context Protocol server for Calibre-Web (and Calibre-Web Automated), the self-hosted ebook library web UI.

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. Search the 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 against the OPDS routes.

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub picks the variant that matches its own theme toggle. npm strips <picture> and <source> when it sanitises the README and keeps the <img>, which is why that fallback brings its own dark card instead of relying on a media query. --> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://calibreweb-mcp.ni-c.de/architecture-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://calibreweb-mcp.ni-c.de/architecture-light.svg"> <img src="https://calibreweb-mcp.ni-c.de/architecture.svg" alt="An MCP client speaks stdio to calibreweb-mcp, which reads the OPDS feed of Calibre-Web over HTTPS with Basic auth" width="800"> </picture>

<!-- Recorded with vhs from docs/demo.tape against the bundled fixture library (docs/demo-server.mjs) — no Calibre-Web instance needed to reproduce it. -->

📖 Full documentation: calibreweb-mcp.ni-c.de

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.

¹ Leave both unset for an instance that allows anonymous browsing; setting only one of them is a configuration error.

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 = "..." }

Tools

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

Tool	Description
search_books	Search by title, author, series, publisher and tags. Calibre-Web returns every match at once; the result is capped client-side (limit, default 50) and reports the real match count.
list_books	Book listings by view: new (default), hot, rated, discover (random), read, unread, or all (optionally narrowed to an initial letter).
list_shelves	Public shelves plus the configured user's own shelves.
get_shelf_books	The books on a shelf, in shelf order.
get_cover	A book's cover, returned as an image the client can display.
get_stats	Total books, authors, categories and series.

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.

Pagination

Feeds are paginated by the instance's books per page setting (default 60); the page size is not client-controllable. Every listing returns pagination.nextOffset when more pages exist — pass it as offset in the next call. The discover view is a random selection and not paginated.

Deliberately out of scope

• No writes. The OPDS feed has none, and this server would not add any.
• No file downloads. Tools return download URLs, not ebook payloads.
• No facet browsing (authors/series/tags/publishers/languages/formats as their own index feeds). search_books covers those lookups; the routes exist and tools for them can be added if there is a real use case.

Safety

• The server is read-only by construction — GET requests only, no state anywhere.
• Book metadata is untrusted third-party data; every result says so, control characters are stripped, and XML entity processing is disabled (documents declaring a DOCTYPE or entities are refused outright).
• Responses are bounded before parsing (8 MB feeds, 1 MB covers) and again before they reach the model (per-book and per-response budgets).
• Feed hrefs are only passed through when they resolve to the configured origin over http(s) — a hostile feed cannot plant javascript:, file: or cross-origin URLs into the results.
• Redirects are refused so the Basic credentials can never be replayed to another host; covers are only passed through for real image content types.
• The password is scrubbed from the process environment at startup, and URLs are credential-redacted before they appear in any log or result.

Container

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

Development

npm install
npm test            # unit tests against a stubbed OPDS feed, no instance needed
npm run lint
npm run build

See CONTRIBUTING.md.

Releasing

1. Update CHANGELOG.md and bump the version in package.json (+ lockfile).
2. npm run lint && npm run test:coverage && npm run build
3. Tag the release: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

License

MIT