Calibreweb MCP Server

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.

📖 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

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

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