# Calibre Library MCP

`calibre-library-mcp` is a local stdio MCP server that lets AI tools search a self-hosted Calibre library over SSH.

It is designed for a common home-lab setup:

- Calibre or Calibre-Web runs on a remote server.
- The Calibre library directory is mounted into a container, commonly at `/books`.
- SSH access to the host is available from the machine running the AI tool.
- Calibre full-text search is enabled so book contents can be queried.

No HTTP service or public port is opened by this MCP server. The AI tool starts it locally and it reaches the Calibre host over SSH.

## Features

- Search book metadata by title or author.
- List recently added books.
- Inspect details for a Calibre book ID.
- Search indexed full text and return snippets.
- Check Calibre full-text index status.
- Optionally trigger a remote index-maintenance script.

## Requirements

- Python 3.11 or newer on the local machine.
- The `mcp` Python package.
- SSH key access from the local machine to the Calibre host.
- Docker on the Calibre host, if you use the default container-based access pattern.
- A Calibre-Web container or equivalent container that can run Python and read the library files.

The default implementation queries SQLite from inside the configured Calibre-Web container with:

```bash
docker exec -i "$CALIBRE_WEB_CONTAINER" python3 ...
```

## Install

Clone the repository:

```bash
git clone https://github.com/<owner>/calibre-library-mcp.git
cd calibre-library-mcp
```

Create a virtual environment and install the package:

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```

## Configuration

Set these environment variables in your MCP client configuration:

| Variable | Required | Description | Example |
| --- | --- | --- | --- |
| `CALIBRE_SSH_HOST` | yes | Hostname or IP address of the Calibre server. | `calibre.example.lan` |
| `CALIBRE_SSH_USER` | yes | SSH user on the Calibre server. | `calibre` |
| `CALIBRE_SSH_KEY` | no | SSH private key path. | `/home/user/.ssh/id_ed25519` |
| `CALIBRE_SSH_PORT` | no | SSH port. Defaults to `22`. | `22` |
| `CALIBRE_WEB_CONTAINER` | no | Container used to query the mounted library. Defaults to `calibre-web`. | `calibre-web` |
| `CALIBRE_CONTAINER_BOOKS_PATH` | no | Library path inside the container. Defaults to `/books`. | `/books` |
| `CALIBRE_REMOTE_LIBRARY_PATH` | no | Library path on the remote host for Calibre CLI status checks. | `/srv/calibre/library` |
| `CALIBRE_DOCKER_IMAGE` | no | Calibre image used for `calibredb` status checks. | `lscr.io/linuxserver/calibre:latest` |
| `CALIBRE_MAINTENANCE_SCRIPT` | no | Optional remote script for refreshing FTS. | `/usr/local/bin/calibre-fts-maintenance.sh` |

## MCP Client Config

Most MCP clients accept a stdio server definition similar to this:

```json
{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/calibre-library-mcp",
      "env": {
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre",
        "CALIBRE_SSH_KEY": "/home/user/.ssh/id_ed25519",
        "CALIBRE_WEB_CONTAINER": "calibre-web",
        "CALIBRE_CONTAINER_BOOKS_PATH": "/books",
        "CALIBRE_REMOTE_LIBRARY_PATH": "/srv/calibre/library"
      }
    }
  }
}
```

If you do not install the package, run it from a checkout:

```json
{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/python",
      "args": ["-m", "calibre_library_mcp.server"],
      "cwd": "/absolute/path/to/calibre-library-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/calibre-library-mcp/src",
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre"
      }
    }
  }
}
```

## Tools

### `calibre_search_books`

Searches metadata by title or author.

Arguments:

- `query`: search text.
- `limit`: maximum results, default `10`.

### `calibre_recent_books`

Lists recently added books.

Arguments:

- `limit`: maximum results, default `10`.

### `calibre_book_details`

Returns metadata, formats, tags, and file names for one Calibre book ID.

Arguments:

- `book_id`: numeric Calibre book ID.

### `calibre_search_text`

Searches extracted full text from Calibre's full-text index.

Arguments:

- `query`: search text.
- `limit`: maximum results, default `10`.
- `snippet_chars`: snippet length, default `500`.

### `calibre_index_summary`

Returns raw index counts by format.

### `calibre_index_status`

Runs Calibre's own `calibredb fts_index status` command through Docker on the remote host.

### `calibre_run_index_maintenance`

Starts the optional remote maintenance script configured by `CALIBRE_MAINTENANCE_SCRIPT`.

## Security Notes

- Use a dedicated SSH key with the least permissions practical.
- Do not publish private hostnames, IP addresses, usernames, or keys in MCP config examples.
- Keep the MCP server local to the AI tool. It does not need to listen on a network port.
- The search tools are read-only. The optional maintenance tool can start a remote script, so configure it only if you want that capability.

## Calibre Full-Text Search

The `calibre_search_text` tool depends on Calibre's full-text search index. See [docs/calibre-full-text-search.md](docs/calibre-full-text-search.md) for setup and maintenance instructions.

## Limitations

- Calibre indexes text it can extract from each book file.
- Scanned PDFs need OCR text layers before they become searchable.
- Images, diagrams, and screenshots are not searchable unless OCR has been applied.
- Very large libraries may take a while to search with simple substring matching.