booklore-MCP

An MCP server for 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, 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

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):

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

OpenAI Codex CLI (~/.codex/config.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