calibre_mcp_server by ajtudela - MCP Server

Calibre MCP Server

An MCP (Model Context Protocol) server that provides tools to interact with a Calibre e-book library, allowing search and retrieval of book metadata through the MCP protocol.

Tools

Tool	Description	Parameters
search_books_by_title	Search books by title pattern with wildcards	`title_pattern: str`
search_authors_by_name	Search authors by name pattern with wildcards	`name_pattern: str`
get_books_by_author	Get all books by a specific author name	`author_name: str`
get_books_by_author_id	Get all books by a specific author ID	`author_id: int`
get_books_by_series	Get all books in a series, ordered by index	`series_name: str`
get_books_by_tag	Get all books with a specific tag	`tag_name: str`
search_books_by_tag_pattern	Search books by tag pattern with wildcards	`tag_pattern: str`
get_book_details	Get complete details for a specific book	`book_id: int`
get_library_stats	Get comprehensive library statistics	—
get_all_tags	Get all available tags in the library	—

Configuration

The server supports flexible configuration through environment variables:

Variable	Default	Description
`CALIBRE_LIBRARY_PATH`	—	Required path to Calibre library
`CALIBRE_DB_FILENAME`	`metadata.db`	Database filename within library
`LOG_LEVEL`	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`LOG_FORMAT`	Default format	Custom logging format string
`MCP_SERVER_NAME`	`Calibre MCP Server`	Server name for MCP protocol
`TRANSPORT_MODE`	`stdio`	Transport mode (`stdio` or `http`)
`HTTP_HOST`	`0.0.0.0`	HTTP host when using HTTP transport
`HTTP_PORT`	`9001`	HTTP port when using HTTP transport

Environment Setup

Copy the example environment file:

cp .env.example .env

Edit .env with your settings:

# Required
CALIBRE_LIBRARY_PATH=/path/to/your/calibre/library

# Optional
LOG_LEVEL=DEBUG
TRANSPORT_MODE=http

Features

Advanced search capabilities: Search books by title, author, series, and tags with wildcard support
Comprehensive metadata: Retrieve complete book information including publication dates, series info, and tags
Library statistics: Get insights into your Calibre library with comprehensive statistics
Tag management: Browse and search through all available tags in your library
Author discovery: Find authors and explore their complete bibliographies
Series tracking: Access books in series with proper ordering by series index

Installation

Install with uv (recommended)

Clone the repository and install with uv:

git clone https://github.com/ajtudela/calibre_mcp_server.git
cd calibre_mcp_server
cp .env.example .env
# Edit .env file with your Calibre library path
uv sync

Or install directly from the repository:

uv add git+https://github.com/ajtudela/calibre_mcp_server.git

Install with pip

Install the package in mode:

git clone https://github.com/ajtudela/calibre_mcp_server.git
cd calibre_mcp_server
cp .env.example .env
# Edit .env file with your Calibre library path
python3 -m pip install .

Or install directly from the repository:

python3 -m pip install git+https://github.com/ajtudela/calibre_mcp_server.git

Usage

Running with uv

uv run calibre_mcp_server

Running with pip installation

python3 -m calibre_mcp_server

HTTP Mode (for containers)

To run in HTTP mode for containerized environments:

# Set environment variable
export TRANSPORT_MODE=http
export HTTP_HOST=0.0.0.0
export HTTP_PORT=9001

Configuration example for Claude Desktop/Cursor/VSCode

Using uv (recommended)

Add this configuration to your application's settings (mcp.json):

{
  "calibre mcp server": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/calibre_mcp_server",
      "calibre_mcp_server"
    ],
    "env": {
        "CALIBRE_LIBRARY_PATH": "YOUR_CALIBRE_LIBRARY_PATH"
    }
  }
}

Using pip installation

{
  "calibre mcp server": {
    "type": "stdio",
    "command": "python3",
    "args": [
      "-m",
      "calibre_mcp_server"
    ],
    "env": {
        "CALIBRE_LIBRARY_PATH": "YOUR_CALIBRE_LIBRARY_PATH"
    }
  }
}

Technical Notes

Database connection: Automatic connection management with proper error handling
Configuration validation: Startup validation ensures all required settings are present
SQLite optimization: Efficient queries with proper indexing and connection pooling
Search patterns: Support for SQL LIKE wildcards (%) for flexible pattern matching
Read-only access: Safe, read-only access to Calibre library database
Memory efficient: Optimized queries and proper resource cleanup
Error recovery: Graceful handling of database errors and network issues

Contributing

Fork the repository
Create a feature branch
Make your changes following the established patterns
Ensure all modules compile without errors
Update documentation as needed
Submit a pull request

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.