Skip to main content
Glama
ispyridis

Calibre MCP Server

by ispyridis
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Related MCP server: calibre-mcp

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

  1. 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.

Feature

Simple Version

RAG Version

Basic Search

✅

✅

Book Reading

✅

✅

Dependencies

None

Many

Memory Usage

Low

High

Vector Search

❌

✅

Semantic Search

❌

✅

OCR Support

❌

✅

Project Organization

❌

✅

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

Available Tools

2 tools
fetchC

Fetch specific content from a book using epub:// URL

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesepub:// URL from search results

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool fetches content but doesn't disclose behavioral traits such as whether it's read-only or mutative, what happens with invalid URLs, rate limits, or authentication needs. This is inadequate for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the purpose and key constraint ('epub:// URL'). There's no wasted text, making it appropriately sized and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (fetching content with a single parameter), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'content' is returned (e.g., text, metadata), error handling, or other behavioral aspects needed for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the parameter 'url' fully documented in the schema. The description adds minimal value by specifying 'epub:// URL from search results', which hints at the source but doesn't provide additional syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('fetch') and resource ('specific content from a book'), and specifies the required input format ('using epub:// URL'). However, it doesn't explicitly differentiate from the sibling 'search' tool, which likely returns URLs rather than content. This makes it clear but not fully sibling-distinctive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling 'search' tool, prerequisites like needing a URL from search results, or any exclusions. This leaves the agent with minimal context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedfetch
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: 'fetch' retrieves specific content from a book using an epub URL, while 'search' performs library-wide queries for books. There is no overlap in functionality, making it impossible to confuse them.

Naming Consistency5/5

Both tool names follow a simple, consistent verb pattern ('fetch' and 'search') that clearly indicates their actions. The naming is straightforward and predictable across the set.

Tool Count2/5

With only 2 tools, this server feels severely under-scoped for managing an ebook library. Essential operations like adding books, updating metadata, deleting entries, or listing books are missing, making it incomplete for typical Calibre workflows.

Completeness2/5

The toolset is highly incomplete for ebook library management. While 'fetch' and 'search' are useful, there are significant gaps: no CRUD operations for books (create, read, update, delete), no library organization tools, and no metadata management beyond search. This will cause agent failures in common tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • archilles

    kasssandr
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables semantic search over local Calibre libraries via MCP, allowing AI assistants to query books, annotations, and export bibliographies while keeping data private.
    7
    MIT

  • calibre-mcp

    gustavofsousa
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables conversational management of a Calibre ebook library via MCP, including search, metadata editing, adding, converting, deduplicating, removing, and emailing books with human-in-the-loop safety.
    1
    MIT

  • calibre-mcp

    monch1962
    A
    license
    Not graded
    quality
    A
    maintenance
    A read-only MCP server for an existing Calibre ebook library, enabling metadata search, full-text search, and category browsing via the Model Context Protocol.
    MIT

  • calibre-mcp

    caelum29
    A
    license
    A
    quality
    A
    maintenance
    Connects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.
    14
    107 npm
    15
    MIT

Appeared in Searches