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

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