Calibre mcp setup

<!-- Cross-agent notes (informational; ignored by host agents): - Compatible skill roots: Claude Code (~/.claude/skills, .claude/skills), GitHub Copilot CLI (~/.copilot/skills, ~/.agents/skills, .github/skills), Amp (.agents/skills, ~/.config/agents/skills). Installable via `npx skills@latest add caelum29/calibre-mcp`. - Needs only shell access (and, for Phase 3, the calibre-mcp tools once loaded). - Windows commands assume PowerShell; macOS/Linux assume any POSIX shell. -->

calibre-mcp setup

Take this machine from "has Calibre" to "calibre-mcp verified working in the user's client(s)". Work phase by phase; a phase is complete only when its VERIFY produced the stated evidence as a tool result in this session — never claim progress without one. If a VERIFY fails twice, stop and report; don't improvise workarounds.

Scope: install + configure + verify, including guiding the user through the Calibre-side configuration (Content Server, write permission). Out of scope: building a whole-library semantic index (offer the command, don't run it), modifying the Calibre library, installing Calibre or Node themselves.

Decisions reserved for the user (never default them yourself): enabling the write gate, starting the Content Server (GUI vs headless daemon), running the index build, and which client(s) to install into.

Phase 0 — Preflight

Check in order. Apply reversible remediations; stop for the rest.

1. Node ≥ 22.5 (not needed for the Claude Desktop .mcpb path — Desktop ships its own runtime): node --version. Missing/old → if the user only wants Desktop, continue; otherwise stop (user installs Node).
2. Calibre present — try calibredb --version, then the platform default:
   • macOS: /Applications/calibre.app/Contents/MacOS/calibredb --version
   • Windows: & "C:\Program Files\Calibre2\calibredb.exe" --version
   • Linux: /usr/bin/calibredb --version Missing → stop; user installs from https://calibre-ebook.com/download. (The server auto-discovers calibredb per platform — a non-default location only needs CALIBRE_MCP_CALIBREDB_PATH later.)
3. Content Server reachable: curl -s http://localhost:8080/interface-data/init (PowerShell: curl.exe, or Invoke-WebRequest). Non-default port → adjust the URL here and set CALIBRE_MCP_SERVER_URL in Phase 2. Not reachable → tell the user: Calibre → Connect/share → Start Content server, or headless calibre-server --port 8080; wait, re-verify. Don't start it yourself — GUI vs daemon is their call. Warn: the two are mutually exclusive — Calibre's server lock is global, so calibre-server refuses to start while the GUI is open ("Another calibre program … is running"). GUI open = use the GUI's own Content Server, nothing else.
4. Optional, note only: pdftotext -v (poppler: brew install poppler / winget install poppler / distro package). Absent = degraded PDF extraction, not a blocker. Footnote it; install nothing.

VERIFY: 2 and 3 green (1 too, unless Desktop-only).

Calibre-side setup (reference — walk the user through, don't click for them)

How Calibre itself should be configured for calibre-mcp. All server access goes through the Content Server; the library database is never touched directly.

1. Install Calibre (user's job): https://calibre-ebook.com/download — any recent version; the server is developed against 9.x.
2. Content Server on, ideally always-on. One-off: Calibre → Connect/share → Start Content server. Better: Preferences → Sharing over the net → enable the run-automatically-at-startup option, so the server survives Calibre restarts and MCP sessions never hit a dead port. Default port 8080 is set on the same page — if changed, mirror it in CALIBRE_MCP_SERVER_URL.
3. Headless alternative (no GUI, e.g. a NAS): calibre-server --port 8080 [--enable-local-write] /path/to/library. Remember the global lock from Phase 0: this cannot run while the GUI is open — pick one.
4. Writes need BOTH gates open (leave both closed for read-only use):
   • Calibre side: Preferences → Sharing over the net → Advanced → "Allow un-authenticated local connections to make changes to the library", then restart the Content Server from the GUI (headless: --enable-local-write). With it off, every routed write returns an actionable "write refused" — this toggle is the first thing to check when that appears.
   • MCP side: CALIBRE_MCP_ENABLE_WRITE=1 (Phase 2). Without it, write tools aren't even advertised.
5. No Content Server auth for localhost. calibre-mcp connects unauthenticated; a user/password-protected Content Server is untested — if the user needs remote auth, keep a separate unauthenticated localhost instance for calibre-mcp or stop and report.
6. Multiple libraries work out of the box: the GUI's server exposes every known library; tools take a library param (display name is fine), and CALIBRE_MCP_LIBRARY sets the default.

Phase 1 — Which client(s)?

Detect the harness you're running in, then ask the user ONE question — where they want calibre-mcp (multiple allowed):

Client	Path
Claude Code	(a) plugin — server + skills + config dialog, auto-updates — or (b) server only
Claude Desktop	(c) .mcpb one-click, or (d) JSON config
Cowork	(e) = configure Claude Desktop; Desktop bridges local servers into Cowork automatically
Anything else (Copilot, Amp, Cursor, Codex, …)	(f) generic MCP config + skills via skills.sh

Don't proceed on a guess.

Phase 2 — Install

(a) Claude Code plugin

claude plugin marketplace add caelum29/calibre-mcp
claude plugin install calibre-mcp@caelum29

Then surface the userConfig options (server URL, library, write gate, add roots) via /plugin configure calibre-mcp@caelum29 or --config KEY=VALUE. Write gate stays OFF unless the user explicitly says otherwise.

(b) Claude Code, server only

claude mcp add calibre -- npx -y calibre-mcp

(c) Claude Desktop .mcpb — user downloads the .mcpb asset from https://github.com/caelum29/calibre-mcp/releases/latest and opens it; Desktop prompts for settings. Manual by design — give the link and stop this branch. Note: the bundle ships without the embeddings dependency (semantic search reports unavailable; keyword FTS works fully).

Enabling semantic search in the .mcpb install (optional, on request): run npm install @huggingface/transformers inside the extension directory (Settings → Extensions → Advanced shows the path; macOS: ~/Library/Application Support/Claude/Claude Extensions/local.mcpb.<id>.calibre-mcp/), then restart the server — toggle the extension off/on in Settings → Extensions, or restart Desktop. The restart is mandatory, not a nicety: Node 24 negatively caches a failed package lookup for the process lifetime, so installing while the server runs NEVER takes effect. This restart-after-install rule applies to every install type (npx, dev checkout too).

(d) Claude Desktop JSON — add to claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\):

{ "mcpServers": { "calibre": { "command": "npx", "args": ["-y", "calibre-mcp"] } } }

Windows: if the server never connects, wrap the command — "command": "cmd", "args": ["/c", "npx", "-y", "calibre-mcp"] (Desktop-on-Windows spawning quirk).

(f) Other MCP clients — emit the same mcpServers block and point the user to their client's MCP-config location (don't guess paths you can't verify). Skills for Agent-Skills-compatible harnesses: npx skills@latest add caelum29/calibre-mcp.

Env vars for any JSON path, all optional: CALIBRE_MCP_SERVER_URL (default http://localhost:8080), CALIBRE_MCP_LIBRARY (display name is fine — libId resolution is internal; empty = server default), CALIBRE_MCP_ENABLE_WRITE (unset = read-only), CALIBRE_MCP_ADD_ROOTS, CALIBRE_MCP_CALIBREDB_PATH, CALIBRE_MCP_RERANK=off (skip the ~576 MB reranker model — see Phase 4).

Reproducibility: npx -y calibre-mcp may serve a stale cached version — pin (npx -y [email protected]) or force latest (calibre-mcp@latest) when it matters.

VERIFY (a/b): claude mcp list shows the calibre server "✔ Connected". VERIFY (c/d/e/f): config file contains the entry (read it back); live check is Phase 3.

Phase 3 — Live verify

In a session where the server is loaded, call the calibre_ping tool — its semantic-status block reports connectivity, library, write-gate state, and semantic-index state in one call. Evidence = the ping result.

Triage the semantic block (don't just echo it):

Ping says	Meaning → action
available: true + counts	Semantic ready; nothing to do
dependencyInstalled: false	Expected for .mcpb / --omit=optional installs; keyword search fully works. Offer the Phase 2(c) enable recipe
dependencyInstalled: true, loaded: "failed" / restartRequired: true	Dep is on disk but this process can't use it — restart the server; nothing else fixes it
modelCached: false	First embedding build will download the ~118 MB model — set expectations
vectorCount 0 / missing with dep OK	No semantic index yet — offer calibre_build_index (Phase 4)

A client can't see a server registered mid-session: if calibre_ping isn't available here, say so, and give the user the exact post-restart check ("restart, then ask: ping my calibre library"). Never simulate or predict the result.

Phase 4 — Offer, don't execute

• Semantic search: first calibre_build_index downloads multilingual-e5-small (~118 MB, one-time) and pre-warms the cross-encoder reranker (bge-reranker-v2-m3, ~576 MB one-time) — warn about the size before the first build; CALIBRE_MCP_RERANK=off skips the reranker (search still works, fused order only). Suggest starting with a subset (one tag / a few ids). keywordOnly: true = the zero-ML fallback. Models + index live in the shared data dir (macOS: ~/Library/Application Support/calibre-mcp/index; Linux: $XDG_DATA_HOME or ~/.local/share/…; Windows: %APPDATA%-based) — plan for ~700 MB+ with both models.
• Companion skills (if not installed via plugin/skills.sh): calibre-mcp usage guide, calibre-distill, calibre-distill-topic.

Upgrade / uninstall / clean slate

Upgrade (per install type):

• Claude Code plugin: auto-updates; force with claude plugin update calibre-mcp@caelum29.
• npx paths: usually picks up new versions, but the npx cache can serve a stale one — npx -y calibre-mcp@latest, or pin explicitly.
• Claude Desktop .mcpb: download the new release asset and open it — installing over the old version is the upgrade path. A manually-installed @huggingface/transformers inside the old extension dir does NOT carry over — re-run the Phase 2(c) enable recipe (incl. restart) after upgrading.
• After any upgrade the server restarts with the client; re-verify with calibre_ping.

Uninstall: claude plugin uninstall calibre-mcp@caelum29 / claude mcp remove calibre / delete the mcpServers entry / remove the extension in Desktop Settings. The shared data dir (index + models, Phase 4 locations) is NOT removed by any of these — deleting it is the user's call; a rebuilt index restores everything except the one-time model downloads.

Clean slate (index corrupt / wrong model state): stop the client, delete the shared data dir, restart, rebuild the index. Never delete the Calibre library itself.

Final report

phase 0: node <ver> | calibredb <ver> @ <path> | content-server OK/FAIL | pdftotext yes/no
phase 2: <client(s)> → <command results>
phase 3: <calibre_ping block, or the post-restart instruction>
write gates: MCP ON/OFF | calibre-side local-write ON/OFF/unknown (user's decision)
offered, not run: <list>
stops hit: <list or none>

Done = phases 0–3 verified. Anything reported without a tool result in this session is a failure of this setup, not a success.