booklore-mcp

A Model Context Protocol (MCP) server for BookLore — your self-hosted digital library manager.

Connect Claude (or any MCP-compatible AI client) directly to your BookLore instance to search your library, check reading progress, update statuses and ratings, browse series, explore highlights, and more — all through natural conversation.

---

Requirements

• BookLore v2.x running and accessible
• Node.js 22+
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

---

Installation

From GitHub Packages (recommended)

1. Add the scope registry to your project's .npmrc (or ~/.npmrc):

   @cyberglitchlabs:registry=https://npm.pkg.github.com
   

2. Authenticate with a GitHub personal access token that has read:packages scope:

   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
   

3. Install the package:

   npm install -g @cyberglitchlabs/booklore-mcp
   

From source

git clone https://github.com/cyberglitchlabs/booklore-mcp.git
cd booklore-mcp
npm install
npm run build

---

Configuration

BookLore MCP supports two authentication methods.

Option A — API token (recommended if available)

1. Log in to your BookLore instance
2. Go to Settings → Profile
3. Copy your API token

Option B — Username / password

If you don't have easy access to an API token, you can authenticate with your BookLore username and password. The server will log in on startup, cache the access token, and automatically refresh it when it expires.

Environment variables

Variable	Required	Default	Description
BOOKLORE_BASE_URL	❌	http://localhost:6060	Base URL of your BookLore instance
BOOKLORE_TOKEN	✅ (Option A)	—	Your BookLore API token
BOOKLORE_USERNAME	✅ (Option B)	—	BookLore username
BOOKLORE_PASSWORD	✅ (Option B)	—	BookLore password

Set either BOOKLORE_TOKEN or BOOKLORE_USERNAME + BOOKLORE_PASSWORD — not both.

---

Claude Desktop setup

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

If installed via npm

Option A — API token:

{
  "mcpServers": {
    "booklore": {
      "command": "booklore-mcp",
      "env": {
        "BOOKLORE_TOKEN": "your-token-here",
        "BOOKLORE_BASE_URL": "http://localhost:6060"
      }
    }
  }
}

Option B — Username / password:

{
  "mcpServers": {
    "booklore": {
      "command": "booklore-mcp",
      "env": {
        "BOOKLORE_USERNAME": "your-username",
        "BOOKLORE_PASSWORD": "your-password",
        "BOOKLORE_BASE_URL": "http://localhost:6060"
      }
    }
  }
}

If installed from source

Replace "command": "booklore-mcp" with:

"command": "node",
"args": ["/absolute/path/to/booklore-mcp/dist/index.js"]

Restart Claude Desktop after saving.

---

Available tools

Books

Tool	Description
search_books	Search and filter books by title, author, library, shelf, status, rating, language, and file type
get_book	Full book details — metadata, progress, files, shelves, Goodreads rating
update_book_rating	Set personal rating (1–5)
update_book_status	Set read status (WANT_TO_READ, IN_PROGRESS, READ, DNF)
get_continue_reading	Books currently in progress
get_recently_added	Most recently added books

Libraries

Tool	Description
list_libraries	List all libraries with book counts and allowed formats
get_library_books	Browse books in a specific library

Shelves

Tool	Description
list_shelves	List all user-created shelves
list_magic_shelves	List all smart/auto-populated shelves
get_magic_shelf_books	Browse books on a specific magic shelf

Series

Tool	Description
list_series	List or search series with reading progress
get_series_books	Get all books in a specific series

Authors

Tool	Description
list_authors	List or search authors
get_author	Author bio and book count
get_author_books	All books by a specific author

Notebooks

Tool	Description
list_notebook_books	Books that have highlights or notes
get_book_notebook_entries	All highlights and notes for a specific book

---

Usage examples

"What books am I currently reading?"

"Search for sci-fi books I haven't read yet, sorted by most recently added"

"Show me all books in the Dune series"

"What are my highlights from Project Hail Mary?"

"Mark book 42 as read and give it a 5-star rating"

"List all my libraries"

---

Development

# Run in watch mode (auto-recompile on change)
npm run dev

# Type-check without emitting
npx tsc --noEmit

# Build for production
npm run build

# Run tests
npm test

# Lint
npm run lint

---

Disclaimer

BookLore's API is internal and unversioned — it may change between BookLore releases without notice. This MCP server targets BookLore v2.x. If your BookLore instance is updated and tools start failing, check whether the API endpoints or response shapes have changed.

---

License

MIT