calibremcp

FastMCP 3.4+ server for conversational Calibre e-book library management. Reads Calibre's metadata.db directly (local SQLite, no Content Server required), indexes metadata for semantic search via LanceDB, and exposes portmanteau MCP tools for natural-language library management.

Install

Requires Python 3.12+ and uv.

git clone https://github.com/moranon/calibremcp
cd calibremcp
uv sync

Configure

Create a .env file (see .env.example):

# Single library
CALIBRE_LIBRARY_PATH=/path/to/your/Calibre Library

# OR: root dir containing multiple sub-libraries
CALIBRE_LIBRARY_ROOT=/path/to/libraries

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "calibre-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/calibremcp", "run", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/path/to/your/Calibre Library"
      }
    }
  }
}

HTTP transport

MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=10720 uv run calibre-mcp

stdio (the default) uses no port. MCP_PORT only applies to the http/sse transports and defaults to 10720.

Tools

Most tools follow the portmanteau pattern — a single tool name with an operation parameter. The table below lists the actual operations each handler accepts.

These tools are not portmanteaus (no operation parameter):

show_api_docs (a machine-readable tool catalog) is always registered. When CALIBRE_PREFAB_APPS is enabled (the default), two MCP-App UI cards are also registered: show_book_prefab_card and show_libraries_prefab_card.

RAG / semantic search

calibremcp includes two LanceDB backends, both stored inside the active library directory:

• FTS content index (lancedb/books_rag) — semantic search over book passages using Calibre's full-text search data (fts_index_build / fts_retrieve). Requires FTS to be enabled in Calibre.
• Metadata index (lancedb_metadata/) — semantic search over titles, authors, tags, series, comments (metadata_index_build / metadata_search).

Index builds run as background jobs and return a job_id immediately:

manage_rag(operation="fts_index_build")
→ {"job_id": 1, "status": "pending"}

manage_rag(operation="job_status", job_id=1)
→ {"status": "done", "result": {"chunks_indexed": 42381}}

manage_rag(operation="fts_retrieve", query="murder mystery with a locked room")

Recommendations

manage_recommendations turns the metadata index into a recommendation engine — no embedding model is loaded (it reuses the vectors stored at index-build time):

manage_recommendations(operation="similar_books", book_id=42)   # more like this
manage_recommendations(operation="for_you")                      # picks from your ratings + read history
manage_recommendations(operation="discover", min_age_days=365)   # unread hidden gems in your backlog

The taste profile is built from books rated ≥ min_rating stars (default 4) and books marked read (CALIBRE_READ_COLUMN); both signals degrade gracefully when absent. Requires the metadata index (manage_rag(operation="metadata_index_build")).

Environment variables

Anna's Archive downloads

manage_import operation="annas_download" tries, in order: the member fast-download API (set CALIBRE_ANNAS_SECRET_KEY), then free external mirror links over plain HTTP. When those are all blocked by Anna's DDoS-Guard JS challenge, it can fall back to a headless Chromium browser that solves the challenge and drives the free slow-download flow.

That fallback is an optional extra (it is lazily imported — everything else works without it). From the project directory:

uv sync --extra browser            # installs Playwright into the project venv
uv run playwright install chromium # one-time Chromium download (~150 MB)

If a CalibreMCP server is already running from this venv, stop it first — uv sync rewrites the launcher scripts and Windows will block that while the server holds them open.

Tune the overall browser session timeout with CALIBRE_ANNAS_BROWSER_TIMEOUT (seconds, default 180).

Safety / write policy

Close the Calibre GUI before writes. Calibre keeps metadata.db open and holds an in-memory cache; if the GUI is running it can overwrite changes written underneath it.

How writes are routed:

• Core metadata (title, sort, pubdate, series/series_index, authors, author_sort, tags, rating, comments) is written directly to metadata.db via SQLite (SQLAlchemy). The connection registers Calibre's own title_sort() function (db/database.py) so Calibre's triggers fire and derived sort fields stay consistent. Writes are read-back verified — a tool reports success: True only after confirming the change persisted.
• Covers and fields not yet in the ORM (isbn, publisher, languages) are not written directly; they route through the calibredb subprocess (with a timeout) or are reported as unsupported for manual calibredb use.
• There is no second database: background job history for RAG index builds is held in memory (per server process) and cleared on restart.

The HTTP transport holds the active library in process-global state and is intended for single-client / local use; it is not isolated for concurrent multi-client access (a library switch changes the active library for the whole process). Use stdio for Claude Desktop.

License

MIT