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