Calibre Librarian MCP Server

Model Context Protocol (MCP) server that surfaces your Calibre catalog to Claude via xmcp.

Requirements

• Node.js: v24.13.0 (auto-managed if you use nvm use).

• pnpm: version 10.28.0 or newer.

• Calibre CLI tools: calibredb and ebook-convert must be installable on your PATH.

• Environment variables:

  • CALIBRE_LIBRARY_PATH – absolute path to your Calibre library directory.

  • CALIBRE_DB_COMMAND – location of the calibredb executable (e.g., /opt/homebrew/bin/calibredb).

  • FAVORITE_SEARCH_ENGINE_URL – base URL used when the server offers external book lookups (defaults to DuckDuckGo: https://duckduckgo.com/?q=).

Setup

1. Clone and enter the repo:

   git clone https://github.com/chepetime/calibre-librarian-mcp.git
   cd calibre-librarian-mcp

2. Install dependencies with pnpm:

   pnpm install

3. Copy the sample environment file and fill in your paths:

   cp .env.example .env

Update the variables so the server can reach your Calibre library.

The env is just for local development. For Claude Desktop, you'll need to configure the server in the Claude Desktop settings.

Local development workflow

Use these scripts while iterating locally:

• pnpm run dev – watches files and serves the MCP server over stdio.

• pnpm run lint – type-checks and lints the project.

• pnpm test – runs the full unit test suite once.

• pnpm test:watch – reruns tests whenever source files change.

Build for Claude Desktop (no Docker)

Follow this flow when you want Claude Desktop (or any MCP client) to run the compiled server directly:

1. Build the project so dist/stdio.js exists:

   pnpm run build

2. (Optional) Run the built output locally for a quick smoke test:

   pnpm start  # equivalent to: node dist/stdio.js

3. Configure Claude Desktop by editing ~/Library/Application Support/Claude/claude_desktop_config.json (or via the in-app UI). Set command to node, include the absolute path to dist/stdio.js as the first args entry, and provide the required environment variables:

{
  "globalShortcut": "",
  "mcpServers": {
    "calibre-librarian": {
      "command": "node",
      "args": ["/Users/you/path/to/calibre-librarian-mcp/dist/stdio.js"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "<Absolute path to your>/Calibre",
        "CALIBRE_DB_COMMAND": "/opt/homebrew/bin/calibredb",
        "FAVORITE_SEARCH_ENGINE_URL": "https://duckduckgo.com/?q="
      }
    }
  },
  "preferences": {
    "quickEntryShortcut": "off",
    "menuBarEnabled": false
  }
}

After Claude Desktop reloads, it will list calibre-librarian as an available MCP server whenever MCP-enabled conversations start.

Docker deployment

Run the server in a container with Calibre pre-installed when you prefer an isolated environment.

Quick start

# Build the image
docker build -t calibre-librarian-mcp .

# Run with your Calibre library mounted
docker run -it \
  -v /path/to/your/calibre/library:/library:ro \
  -e CALIBRE_LIBRARY_PATH=/library \
  calibre-librarian-mcp

Docker Compose

1. Copy and customize docker-compose.yml.

2. Set your library path and launch the stack:

   export CALIBRE_LIBRARY_PATH=/path/to/your/calibre/library
   docker compose up --build

Claude Desktop with Docker

To let Claude Desktop run the container directly, point it at docker run:

{
  "mcpServers": {
    "calibre-librarian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/calibre/library:/library:ro",
        "-e",
        "CALIBRE_LIBRARY_PATH=/library",
        "calibre-librarian-mcp"
      ]
    }
  }
}

Note: Remove :ro from the volume mount and add -e CALIBRE_ENABLE_WRITE_OPERATIONS=true to enable write operations.

Tool Catalog & Examples

Installing the MCP CLI

The examples below use the mcp CLI published by Anthropic. Install (or run) it with any of the following options:

• Global install (recommended if you call MCP tools frequently):

  npm install -g @anthropic-ai/mcp-cli
  # now `mcp --help` should work

• One-off execution without a global install:

  npx @anthropic-ai/mcp-cli --help
  # or
  pnpm dlx @anthropic-ai/mcp-cli --help

CLI usage

All tools can be invoked from MCP Inspector or the CLI:

mcp call calibre-librarian <toolName> '<json payload>'

Prompts (e.g., merge_duplicates, library_cleanup, search_library) use the companion command:

mcp prompt calibre-librarian library_cleanup '{"focus":"missing covers"}'

Swap library_cleanup for any prompt listed below, and replace calibre-librarian with the server name you configured in mcp.json.

Library Overview & Metadata

Search & Discovery

Full-Text & Content Access

Cleanup & Duplicate Workbench

Smart Maintenance Recipes

Metadata Editing & Custom Columns

Requires CALIBRE_ENABLE_WRITE_OPERATIONS=true

Setup & Configuration Tools

Environment Variables

Resources

The server exposes these MCP resources:

Troubleshooting

"calibredb: command not found"

The server can't find the Calibre CLI tools. Solutions:

• macOS (Homebrew): brew install calibre or set CALIBRE_DB_COMMAND=/Applications/calibre.app/Contents/MacOS/calibredb

• macOS (App): CALIBRE_DB_COMMAND=/Applications/calibre.app/Contents/MacOS/calibredb

• Windows: CALIBRE_DB_COMMAND=C:\Program Files\Calibre2\calibredb.exe

• Linux: Install Calibre via package manager, usually adds calibredb to PATH

"Library path does not exist"

Verify your CALIBRE_LIBRARY_PATH:

# Check the path contains metadata.db
ls "$CALIBRE_LIBRARY_PATH/metadata.db"

"Write operations are disabled"

Write tools (set_metadata, set_custom_column, bulk_retag with preview:false, etc.) require:

CALIBRE_ENABLE_WRITE_OPERATIONS=true

Add this to your .env file or Claude Desktop config.

"Command timed out"

For large libraries, increase the timeout:

CALIBRE_COMMAND_TIMEOUT_MS=60000  # 60 seconds

"Full-text search returns no results"

Calibre FTS must be enabled:

1. Open Calibre

2. Go to Preferences → Searching

3. Enable Full text searching

4. Click Re-index all books

Server not appearing in Claude Desktop

1. Verify the config file path:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Check JSON syntax is valid

3. Restart Claude Desktop completely

4. Check Claude Desktop logs for errors

Testing with MCP Inspector

Use the built-in verification guide:

# Start dev server
npm run dev

# In another terminal, run inspector
npx @anthropic/mcp-inspector

Or use the generate_claude_config tool to get your configuration.

License

MIT