pshap/mcp-neolibrarian

Neolibrarian MCP: Calibre Library (Read‑only)

Minimal MCP server exposing read‑only access to a local Calibre library. Designed for use with MCP‑compatible hosts (e.g., Claude Desktop) to search metadata, inspect formats, and extract small content samples for analysis.

What it does

• Connects to your existing Calibre library (local filesystem)
• Exposes read‑only tools: library stats, searches (author/title/unified), per‑book details and formats, full‑text search (global and per‑book, if your Calibre FTS DB exists), small content samples, and batch metadata
• Provides two lightweight JSON resources for quick at‑a‑glance info

Requirements

• Python 3.12+ (3.13 supported)
• Calibre installed locally (calibre‑debug.exe available)
• Access to your Calibre library directory (contains metadata.db)

Install

# From repo root (Windows PowerShell)
python -m venv .venv
./.venv/Scripts/Activate.ps1
pip install -r requirements.txt

Configuration

Place a JSON config file with at least these keys:

{
	"calibre_library_path": "C:/Path/To/Calibre Library",
	"calibre_installation_path": "C:/Program Files/Calibre2"
}

Resolution/precedence (first match wins):

• Environment variable CALIBRE_CONFIG_PATH (absolute or ~-expanded path)
• config.local.json next to the server script
• config.json next to the server script

Run the MCP server

The server runs over stdio for MCP hosts.

./.venv/Scripts/python.exe calibre_mcp_server.py

For MCP hosts (e.g., Claude Desktop), point the tool to this script; optionally set CALIBRE_CONFIG_PATH to your config file.

Exposed tools (read‑only)

• ping → quick health check and paths
• get_total_books
• search_by_author(author_name)
• search_by_title(title)
• unified_search(query?, author?, title?, series?, formats?, date_start?, date_end?, offset=0, limit=20, sort_by)
• get_book_details(book_id)
• get_book_formats(book_id)
• get_book_sample(book_id, sample_type, sample_size)
• analyze_book_content(book_id, analysis_type, max_length)
• full_text_search(query, case_sensitive?, max_results?, context_chars?)
• full_text_search_book(book_id, query, case_sensitive?, context_chars?)
• get_books_batch([book_ids])
• get_random_books(count?, formats?, series_only?)
• get_full_text_search_stats()

Resources:

• calibre://stats (application/json)
• calibre://book/{book_id}/details (application/json)

Notes

• This server is strictly read‑only (no writes to your library).
• Full‑text search tools require Calibre’s full‑text database to exist in your library folder (full‑text-search.db*).

License: MIT (see LICENSE)