# CalibreMCP

<p align="center">
  <a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
  <a href="https://biomejs.dev"><img src="https://img.shields.io/badge/Linted_with-Biome-60a5fa?style=flat-square&logo=biome&logoColor=white" alt="Biome"></a>
  <a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.4.2+-7c5cfc?style=flat-square" alt="FastMCP"></a>
  <a href="https://tauri.app"><img src="https://img.shields.io/badge/Tauri-2.0-ffc131?style=flat-square&logo=tauri&logoColor=white" alt="Tauri"></a>
  <a href="https://github.com/Jarzembak/calibremcp/releases"><img src="https://img.shields.io/github/v/release/Jarzembak/calibremcp?style=flat-square&logo=github" alt="Release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License"></a>
</p>


> 📖 **[Installation Guide](INSTALL.md)** — source installation is available now; packaged desktop and MCPB artifacts will be available after the fork's first release

**FastMCP 3.4.2+ MCP server for Calibre e-book library management, AI-assisted search, RAG, and agentic workflows.**

## Naming

- Repository and Python distribution: `calibremcp`
- Python import package: `calibre_mcp`
- Command-line executable: `schip-mcp-calibre`
- Product name: CalibreMCP

The hyphenated `calibre-mcp` form remains only where it is an established external
identifier, such as the application-data directory.

## Quick Start

The detached fork has not published a release yet. Run it from source:

```powershell
git clone https://github.com/Jarzembak/calibremcp.git
cd calibremcp
uv sync
uv run schip-mcp-calibre --http
# --http starts the HTTP transport on the configured CalibreMCP port.
```

`claude_desktop_config.json`:

```json
{
"mcpServers": {
"calibremcp": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\calibremcp", "schip-mcp-calibre"],
"env": {
"CALIBRE_LIBRARY_PATH": "C:\\path\\to\\Calibre Library"
}
}
}
}
```

The `--directory` argument makes `uv` run the executable from the cloned
CalibreMCP project.

For file-based configuration, copy `config.example.json` to the ignored local
file `config.json` and replace the placeholder values. Environment variables
override values from that file.

Then ask Claude: *"Find unread sci-fi books"*, *"Open a random Banks novel"*, or *"What's my library health?"*

## What is this?

CalibreMCP bridges your Calibre e-book library and AI assistants (Claude Desktop, Cursor, etc.) via the Model Context Protocol. It reads Calibre's `metadata.db` directly, indexes metadata for semantic search (LanceDB RAG), and exposes portmanteau tools, analysis helpers, and interactive cards for natural-language library management.

## Read more

| Topic | Description |
|-------|-------------|
| [About Calibre](docs/ABOUT_CALIBRE.md) | What Calibre is, how it stores data, access methods |
| [About Calibre Web](docs/ABOUT_CALIBRE_WEB.md) | calibre-web vs Calibre Content Server, running both together |
| [About Plugins](docs/ABOUT_PLUGINS.md) | CalibreMCP Integration plugin, calibreops-bridge, roadmap |
| [About MCP Tools](docs/ABOUT_MCP_TOOLS.md) | 33 registered tools, portmanteau architecture, agentic flows |
| [About AI Workflows](docs/ABOUT_AI_WORKFLOWS.md) | RAG, FTS, skills, prompts, sampling, agentic chaining |

## Key links

- **[Documentation hub](docs/README.md)** — curated entry
- **[Documentation index](docs/DOCUMENTATION_INDEX.md)** — full map of ~100 docs
- **[Tauri desktop](docs/TAURI.md)** — maintainer build and production pitfalls
- **[Cookbook](docs/COOKBOOK.md)** — goal-oriented recipes
- **[API reference](docs/API.md)** — all MCP tools and endpoints
- **[Configuration](docs/Configuration.md)** — env vars and library setup
- **[Troubleshooting](docs/Troubleshooting.md)** — common issues and fixes
- **[Webapp README](webapp/README.md)** — Next.js dashboard on ports 10720/10721
- **[Plugin README](calibre_plugin/README.md)** — Calibre GUI plugin install and usage
- **[Plugin repo](https://github.com/sandraschi/calibre-plugins)** — calibreops-bridge (RAG/AI plugin)

## Installation

```powershell
# Development install
git clone https://github.com/Jarzembak/calibremcp.git
cd calibremcp
uv sync

# Run the stdio MCP server
uv run schip-mcp-calibre
```

After the first fork release is published, Claude Desktop bundle installations
will use `calibremcp-v<version>.mcpb` from
[Releases](https://github.com/Jarzembak/calibremcp/releases).

## Features

- **FastMCP 3.4.2+** — Universal connect (stdio + HTTP), sampling, agentic tool chaining
- **Consolidated MCP tools** — Search, management, export, RAG, analysis, and viewer operations
- **Metadata RAG (LanceDB)** — Semantic search over title, authors, tags, comments
- **Full-text chunk RAG** — FTS-driven book content retrieval
- **Calibre FTS** — Phrase search with PDF page / EPUB spine locations
- **Calibre plugin** — Extended metadata editor + VL from query in Calibre GUI
- **Webapp** — Next.js dashboard with AI chat, Semantic Search, Skills, Smart Import
- **Skills & prompts** — Reusable agentic workflows (recommendations, library health, etc.)
- **Concurrency-safe** — Thread-safe DB operations for multi-client access
- **Windows-native** — Unicode-safe, runs reliably on Windows

*Austrian efficiency for digital libraries. Built with realistic AI-assisted development timelines.*