mcpField
C
calibredb

calibredb

github.com/lvtd-llcDocuments175 installsUpdated 7w ago
Repository

About calibredb

The CalibreDB skill provides guidance for command-line operations on Calibre libraries, for users who need to inspect or maintain book records. It emphasizes identifying the library path, starting with read-only checks, and confirming intent before destructive operations.

Key features

  1. 01Target a local library or Content server
  2. 02Search books and inspect metadata
  3. 03Add books and update fields
  4. 04Run library health checks
  5. 05Distinguish read-only from destructive operations

Use cases

  1. 01Find books and retrieve record IDs
  2. 02Review book records and format information
  3. 03Update metadata or add book files
  4. 04Check library health

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lvtd-llc/skills --skill calibredb

After installing, type/calibredbin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
command-matrix.md
safe-workflows.md
scripts/
list_books_json.py

Details

From the project README

CalibreDB

Use this skill for all command-line operations on Calibre libraries.

Library path

  • Calibre library locations are user-specific. Identify the target library path or Content server URL before running commands.
  • Prefer explicit path in every command: --with-library "$CALIBRE_LIBRARY".
  • If the user has not provided a library path, ask for it or inspect the local environment for an existing Calibre library before proceeding.
  • For machine-readable outputs, use --for-machine or JSON-capable subcommands.

Safety model

Start with read-only operations, then escalate only when needed.

Read-only (safe by default)
  • list
  • search
  • show_metadata
  • custom_columns
  • list_categories
  • check_library
  • fts_search
  • fts_index status
Mutating (confirm intent for destructive/irreversible)
  • Usually safe with clear intent: add, set_metadata, set_custom, add_format, embed_metadata, backup_metadata
  • Confirm before destructive actions: remove, remove_format, remove_custom_column, restore_database, fts_index reindex on full library

Core workflow

  1. Identify target library and set --with-library.
  2. Discover relevant book IDs with search (or list --search).
  3. Inspect records with show_metadata or list --for-machine.
  4. Apply minimal required mutations.
  5. Validate with follow-up list/search/show_metadata.

Quick command patterns

1) List books
export CALIBRE_LIBRARY="/path/to/Calibre Library"
calibredb list --with-library "$CALIBRE_LIBRARY" --fields id,title,authors,formats --limit 20

Machine output:

calibredb list --with-library "$CALIBRE_LIBRARY" --fields id,title,authors,tags,formats --for-machine
2) Search and get IDs
calibredb search --with-library "$CALIBRE_LIBRARY" "title:python"

Use IDs in follow-up commands.

3) Show metadata
calibredb show_metadata --with-library "$CALIBRE_LIBRARY" 123

As OPF:

calibredb show_metadata --with-library "$CALIBRE_LIBRARY" --as-opf 123
4) Update metadata fields
calibredb set_metadata --with-library "$CALIBRE_LIBRARY" 123 \
  --field title:"Example Book" \
  --field tags:"python,reference"
5) Add/export books
calibredb add --with-library "$CALIBRE_LIBRARY" "/path/to/book.epub"
calibredb export --with-library "$CALIBRE_LIBRARY" 123 --to-dir "/tmp/export"
6) Library health check
calibredb check_library --with-library "$CALIBRE_LIBRARY"

Content server usage

To target a running Calibre Content server:

calibredb list --with-library "http://hostname:8080/#library_id" --username <user> --password <pass>

From docs: use special #- library id to list server libraries.

Security note: a literal --password <pass> value is passed as a process argument and may be visible to other users on shared machines via process-listing tools. Prefer --password '<stdin>' with the password piped from a password manager, or --password '<f:/path/to/file>' with a 0600 credential file stored outside the repository. Prefer local or trusted hosts for authenticated Content server commands, and redact credentials from shell history, logs, and task transcripts.

Reference files

  • Command matrix + options: references/command-matrix.md
  • Safe operational playbooks: references/safe-workflows.md

Comments

Markdown supported