Lyceum

An MCP server for querying and managing a Calibre ebook library via chat. Works with claude.ai and Claude Code. Talks to Calibre's built-in content server over HTTP — no direct database access or CLI tools needed.

Setup

npm install

Requires a running Calibre content server. You can start one from the Calibre GUI (Preferences > Sharing over the net) or from the command line:

calibre-server /path/to/library

Environment Variables

Variable	Required	Default	Description
AUTH_PASSWORD	Yes	—	Password for the OAuth authorization page
CALIBRE_SERVER_URL	No	http://localhost:8080	URL of the Calibre content server
CALIBRE_LIBRARY_ID	No	—	Library ID (only needed for multi-library setups)
CALIBRE_USERNAME	No	—	Username for Calibre content server (Digest auth)
CALIBRE_PASSWORD	No	—	Password for Calibre content server (Digest auth)
BASE_URL	No	http://localhost:3000	Public URL of this server (used for OAuth redirects and signed URLs)
AUTH_STATE_FILE	No	/data/auth-state.json	Path to persist OAuth state (clients, tokens) across restarts
PORT	No	3000	Port to listen on

Running

AUTH_PASSWORD=your-secret npm run dev

For production:

AUTH_PASSWORD=your-secret \
  CALIBRE_SERVER_URL=http://calibre:8080 \
  BASE_URL=https://lyceum.yourdomain.com \
  npm start

Container

Pre-built images are available from GitHub Container Registry:

podman pull ghcr.io/matthewp/lyceum:latest

The container exposes port 3000. Mount a volume at /data to persist OAuth state across restarts:

podman run -d \
  -p 3009:3000 \
  -v lyceum-data:/data \
  -e AUTH_PASSWORD=your-secret \
  -e CALIBRE_SERVER_URL=http://calibre:8080 \
  -e BASE_URL=https://lyceum.yourdomain.com \
  ghcr.io/matthewp/lyceum:latest

To build from source instead, the included Containerfile uses node:24-slim. Node 24 supports native TypeScript type stripping, so no build step is needed — the source runs directly with --experimental-strip-types.

podman build -t lyceum .

For sensitive values, use podman secrets:

printf 'your-secret' | podman secret create lyceum_auth_password -

Then reference them in a quadlet .container file:

Secret=lyceum_auth_password,type=env,target=AUTH_PASSWORD

MCP Tools

Tool	Description
list_books	List books sorted by most recently added
get_book	Get full details for a book (authors, tags, series, formats, custom columns, etc.)
search_books	Search using Calibre's query syntax (e.g. author:Asimov, tag:sci-fi)
list_authors	List all authors with book counts
list_tags	List all tags with book counts
list_series	List all series with book counts
get_download_link	Get a signed download URL for a book file (expires in 5 minutes)
get_upload_link	Get a signed URL to upload a book via browser (expires in 10 minutes)
set_metadata	Update metadata fields on a book (title, authors, tags, custom columns, etc.)
set_cover	Set a book's cover image from a URL
fetch_metadata	Search Google Books for metadata by title, author, or ISBN
convert_book	Convert a book to a different format (e.g. EPUB to PDF)

Connecting to Claude

claude.ai

Go to Settings > Connectors > Add custom connector and enter your server's /mcp URL (e.g. https://lyceum.yourdomain.com/mcp). You'll be prompted to authenticate via the OAuth flow.

Claude Code

claude mcp add --transport http lyceum https://lyceum.yourdomain.com/mcp

Authentication

Lyceum uses OAuth 2.1 with dynamic client registration. When a client connects, it registers automatically, then the user authenticates with the AUTH_PASSWORD. Sessions are persisted to disk so they survive server restarts.

Download and upload links use HMAC-SHA256 signed URLs so they can be opened in a browser without additional authentication.

Communication with the Calibre content server uses HTTP Digest authentication when CALIBRE_USERNAME and CALIBRE_PASSWORD are set.