ispyridis/calibre-mcp-nodejs

Calibre MCP Server

A lightweight Node.js MCP server for searching and reading books from your Calibre ebook library. Designed specifically for Windows compatibility.

Features

• Library Search: Search your Calibre library by title, author, or content
• Book Reading: Retrieve and read book contents in various formats
• Metadata Access: Get detailed book information and metadata
• Windows Compatible: Optimized for Windows environments
• Zero Dependencies: Lightweight implementation with no external dependencies

Prerequisites

• Node.js >= 16.0.0
• Calibre installed on Windows

Installation

1. Clone this repository:

git clone https://github.com/yourusername/calibre-mcp-nodejs.git
cd calibre-mcp-nodejs

2. Install dependencies:

npm install

Usage

Starting the Server

npm start

Available Tools

• search: Search for books in your Calibre library
• fetch: Retrieve specific content from books using epub:// URLs

Example MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "calibre": {
      "command": "node",
      "args": ["path/to/calibre-mcp-nodejs/server.js"]
    }
  }
}

Configuration

The server automatically detects your Calibre library location. The search looks for Calibre in common installation paths:

• C:\Program Files\Calibre2\
• C:\Program Files (x86)\Calibre2\
• Custom paths via environment variables

API Reference

Search Books

// Search by title
search({ query: "title:\"The Great Gatsby\"" })

// Search by author  
search({ query: "author:\"F. Scott Fitzgerald\"" })

// Full-text search
search({ query: "green light" })

Fetch Book Content

// Fetch specific book content
fetch({ url: "epub://book_id/chapter_1" })

Project Structure

calibre-mcp-nodejs/
├── server.js          # Main MCP server
├── package.json       # Dependencies and scripts
├── test.js            # Test file
├── test.bat           # Windows test script
└── README.md          # This file

Testing

Run the test:

npm test

Or use the Windows batch file:

test.bat

Troubleshooting

Common Issues

1. Calibre Not Found: Ensure Calibre is installed in a standard location
2. Library Access: Make sure the Calibre library is accessible and not locked
3. Permissions: Run with appropriate permissions to access Calibre files

Debug Mode

Set the DEBUG environment variable for verbose logging:

set DEBUG=calibre:*
npm start

Supported Formats

The server supports all formats that Calibre can handle:

• EPUB
• PDF
• MOBI
• AZW/AZW3
• TXT
• HTML
• And many more

Performance

This lightweight server is designed for:

• Fast startup times
• Low memory usage
• Quick search responses
• Minimal system impact

Comparison with RAG Version

This is the lightweight version. For advanced features like vector search, semantic similarity, and RAG capabilities, see calibre-rag-mcp-nodejs.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

Licensed under the Apache License 2.0. See LICENSE file for details.

Support

For issues and questions, please open an issue on GitHub.

Changelog

v2.0.0

• Improved Windows compatibility
• Enhanced search functionality
• Better error handling
• Optimized performance

v1.0.0

• Initial release
• Basic search and fetch functionality
• Windows support