# booklore-MCP

An MCP server for [BookLore](https://github.com/booklore-app/booklore). It lets any
MCP-compatible assistant talk to your BookLore library: recommend books you already
own, organize them into shelves, and send a book to your Kindle, all through
BookLore's own REST API.

Because it speaks the open [Model Context Protocol](https://modelcontextprotocol.io),
it works with any MCP client, for example Claude Code, OpenAI Codex CLI, Cursor, Zed,
and Windsurf. It runs over stdio and has no UI of its own.

## What it can do

| Tool | Purpose |
| --- | --- |
| `list_genres` | List the genres/categories in your library with book counts |
| `search_books` | Search by genre, author, title, free text, minimum rating, or unread only |
| `get_book` | Full detail for one book (description, ratings, shelves) |
| `list_shelves` | List all shelves |
| `create_shelf` | Create a shelf (deduplicates by name) |
| `add_books_to_shelf` | Add books to a shelf by id or name (can auto-create) |
| `list_email_recipients` | List configured email recipients (for example Kindle addresses) |
| `send_to_kindle` | Send a book using BookLore's native send-to-Kindle email feature |

Typical requests, in natural language: "recommend a well rated thriller I have not
read", "create a shelf called Summer and add these five", "send Shogun to my Kindle".

### Rating note

In many libraries `metadata.rating` is empty and the real score lives in
`goodreadsRating` or `amazonRating`. This server computes an effective rating
(rating, then Goodreads, then Amazon) so that sorting and `min_rating` actually work.

## Requirements

- Python 3.10 or newer
- A reachable BookLore instance and a BookLore user account
- For `send_to_kindle`: an email provider (SMTP) and at least one recipient configured
  in BookLore (Settings, Email), and the sender address approved in Amazon's
  Approved Personal Document E-mail List

## Install

```bash
git clone https://github.com/Giorgiofox/booklore-MCP.git
cd booklore-MCP
# install dependencies into a local ./libs folder (works without a virtualenv)
pip install --target ./libs -r requirements.txt
cp .env.example .env   # then edit it
chmod 600 .env
```

Fill in `.env`:

```
BOOKLORE_URL=http://localhost:6060
BOOKLORE_USERNAME=your_user
BOOKLORE_PASSWORD=your_password
# set to false only if the TLS certificate is not valid on this host
BOOKLORE_VERIFY_SSL=true
```

`run.sh` loads `.env`, sets `PYTHONPATH` to `./libs`, and starts the server over stdio.

## Configure your MCP client

Point your client at `run.sh`.

Claude Code, Cursor, and similar (JSON):

```json
{
  "mcpServers": {
    "booklore": {
      "command": "/absolute/path/to/booklore-MCP/run.sh"
    }
  }
}
```

OpenAI Codex CLI (`~/.codex/config.toml`):

```toml
[mcp_servers.booklore]
command = "/absolute/path/to/booklore-MCP/run.sh"
```

Restart the client and approve the `booklore` server when prompted.

## How it authenticates

It logs in with `POST /api/v1/auth/login` to obtain a JWT access token and refreshes it
automatically. Credentials stay local in `.env`, which is git-ignored and never committed.

## License

MIT