Neolibrarian MCP

# 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 ```powershell # 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: ```json { "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. ```powershell ./.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)