Skip to main content
Glama
halimchaibi

calibre-library-mcp

by halimchaibi

Calibre Library MCP

calibre-library-mcp is a local stdio MCP server that lets AI tools search a self-hosted Calibre library over SSH.

It is designed for a common home-lab setup:

  • Calibre or Calibre-Web runs on a remote server.

  • The Calibre library directory is mounted into a container, commonly at /books.

  • SSH access to the host is available from the machine running the AI tool.

  • Calibre full-text search is enabled so book contents can be queried.

No HTTP service or public port is opened by this MCP server. The AI tool starts it locally and it reaches the Calibre host over SSH.

Features

  • Search book metadata by title or author.

  • List recently added books.

  • Inspect details for a Calibre book ID.

  • Search indexed full text and return snippets.

  • Check Calibre full-text index status.

  • Optionally trigger a remote index-maintenance script.

Related MCP server: calibre-manager

Requirements

  • Python 3.11 or newer on the local machine.

  • The mcp Python package.

  • SSH key access from the local machine to the Calibre host.

  • Docker on the Calibre host, if you use the default container-based access pattern.

  • A Calibre-Web container or equivalent container that can run Python and read the library files.

The default implementation queries SQLite from inside the configured Calibre-Web container with:

docker exec -i "$CALIBRE_WEB_CONTAINER" python3 ...

Install

Clone the repository:

git clone https://github.com/<owner>/calibre-library-mcp.git
cd calibre-library-mcp

Create a virtual environment and install the package:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Configuration

Set these environment variables in your MCP client configuration:

Variable

Required

Description

Example

CALIBRE_SSH_HOST

yes

Hostname or IP address of the Calibre server.

calibre.example.lan

CALIBRE_SSH_USER

yes

SSH user on the Calibre server.

calibre

CALIBRE_SSH_KEY

no

SSH private key path.

/home/user/.ssh/id_ed25519

CALIBRE_SSH_PORT

no

SSH port. Defaults to 22.

22

CALIBRE_WEB_CONTAINER

no

Container used to query the mounted library. Defaults to calibre-web.

calibre-web

CALIBRE_CONTAINER_BOOKS_PATH

no

Library path inside the container. Defaults to /books.

/books

CALIBRE_REMOTE_LIBRARY_PATH

no

Library path on the remote host for Calibre CLI status checks.

/srv/calibre/library

CALIBRE_DOCKER_IMAGE

no

Calibre image used for calibredb status checks.

lscr.io/linuxserver/calibre:latest

CALIBRE_MAINTENANCE_SCRIPT

no

Optional remote script for refreshing FTS.

/usr/local/bin/calibre-fts-maintenance.sh

MCP Client Config

Most MCP clients accept a stdio server definition similar to this:

{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/calibre-library-mcp",
      "env": {
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre",
        "CALIBRE_SSH_KEY": "/home/user/.ssh/id_ed25519",
        "CALIBRE_WEB_CONTAINER": "calibre-web",
        "CALIBRE_CONTAINER_BOOKS_PATH": "/books",
        "CALIBRE_REMOTE_LIBRARY_PATH": "/srv/calibre/library"
      }
    }
  }
}

If you do not install the package, run it from a checkout:

{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/python",
      "args": ["-m", "calibre_library_mcp.server"],
      "cwd": "/absolute/path/to/calibre-library-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/calibre-library-mcp/src",
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre"
      }
    }
  }
}

Tools

calibre_search_books

Searches metadata by title or author.

Arguments:

  • query: search text.

  • limit: maximum results, default 10.

calibre_recent_books

Lists recently added books.

Arguments:

  • limit: maximum results, default 10.

calibre_book_details

Returns metadata, formats, tags, and file names for one Calibre book ID.

Arguments:

  • book_id: numeric Calibre book ID.

calibre_search_text

Searches extracted full text from Calibre's full-text index.

Arguments:

  • query: search text.

  • limit: maximum results, default 10.

  • snippet_chars: snippet length, default 500.

calibre_index_summary

Returns raw index counts by format.

calibre_index_status

Runs Calibre's own calibredb fts_index status command through Docker on the remote host.

calibre_run_index_maintenance

Starts the optional remote maintenance script configured by CALIBRE_MAINTENANCE_SCRIPT.

Security Notes

  • Use a dedicated SSH key with the least permissions practical.

  • Do not publish private hostnames, IP addresses, usernames, or keys in MCP config examples.

  • Keep the MCP server local to the AI tool. It does not need to listen on a network port.

  • The search tools are read-only. The optional maintenance tool can start a remote script, so configure it only if you want that capability.

The calibre_search_text tool depends on Calibre's full-text search index. See docs/calibre-full-text-search.md for setup and maintenance instructions.

Limitations

  • Calibre indexes text it can extract from each book file.

  • Scanned PDFs need OCR text layers before they become searchable.

  • Images, diagrams, and screenshots are not searchable unless OCR has been applied.

  • Very large libraries may take a while to search with simple substring matching.

Available Tools

7 tools
calibre_book_detailsB

Get metadata, formats, and library file names for a Calibre book ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It mentions it retrieves data but does not clarify that it is read-only, idempotent, or what happens if the book_id does not exist. The output schema is not detailed.

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?

Single sentence that is direct and efficient. No extraneous words or redundancy.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, output schema exists), the description provides the essential purpose. Minor omission: it does not state that the output is a single object or that the book_id must be valid.

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?

With 0% schema coverage, the description partially compensates by linking the parameter 'book_id' to 'Calibre book ID'. However, it does not explain the integer format, required source, or any constraints beyond being required.

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

Purpose5/5

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

The description clearly specifies the action ('Get'), the resource ('metadata, formats, and library file names'), and the identifier ('Calibre book ID'). It is distinct from sibling tools which deal with indexing, searching, or summaries.

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?

No guidance on when to use this tool versus alternatives like calibre_search_books or calibre_index_status. The description assumes the user already has a book ID without explaining how to obtain one or when to prefer this tool.

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

calibre_index_statusA

Return Calibre's own full-text indexing status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

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

No annotations are provided, so the description must fully convey behavior. It only states it returns status, but does not disclose whether it's read-only, the nature of the status (e.g., string, object), or any side effects. Minimal transparency for a tool with no annotations.

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?

A single sentence that is direct and to the point. No wasted words; every part contributes to understanding the tool's purpose.

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

Completeness4/5

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

Given the tool's simplicity (no parameters, output schema exists), the description covers the essential purpose. However, without annotations, a brief note on read-only nature or typical use would enhance completeness.

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

Parameters4/5

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

The tool has zero parameters, so schema coverage is 100% trivially. The description adds no parameter information, but the baseline for 0 parameters is 4. No additional meaning needed.

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

Purpose5/5

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

The description uses a specific verb 'Return' and clearly identifies the resource 'Calibre's own full-text indexing status'. It distinguishes from sibling tools like calibre_run_index_maintenance (action) and calibre_index_summary (likely different output).

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

Usage Guidelines3/5

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

No explicit when-to-use or alternatives guidance is given, but the zero-parameter nature implies it's a straightforward status check. Usage context is implied but not elaborated.

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

calibre_index_summaryA

Return raw full-text index row counts grouped by format.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior2/5

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

The description lacks behavioral details such as whether the operation is read-only, if it requires any setup, or any side effects. With no annotations, the description should disclose traits like performance or data freshness, but it does not.

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, focused sentence with no extraneous information. It is efficiently front-loaded and every word contributes meaning.

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

Completeness4/5

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

The tool is simple with no parameters and an output schema exists, so the description does not need to explain return format. However, it could mention that the operation is safe or read-only. Overall, it is nearly complete for this straightforward tool.

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

Parameters4/5

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

The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to add parameter meaning beyond the schema. A baseline score of 4 is appropriate.

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

Purpose5/5

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

The description clearly states the action ('Return'), the resource ('raw full-text index row counts'), and the grouping ('by format'). It is specific and distinct from sibling tools like calibre_index_status or calibre_search_books.

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?

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without contextualizing its appropriate use cases or prerequisites.

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

calibre_recent_booksC

List recently added books from the Calibre library.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It does not explain what 'recently added' means (e.g., time window, ordering), nor does it mention the effect of the limit parameter. The description is too sparse to provide adequate transparency.

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

Conciseness3/5

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

The description is a single sentence, which is concise, but it omits important information about parameters and behavior. It earns its space but could be more informative without sacrificing brevity.

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 has one parameter, no annotations, and an output schema, the description is incomplete. It does not explain the output format, the meaning of 'recently', or how the limit parameter affects results. More detail is needed for a complete understanding.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not mention the 'limit' parameter at all. Since the description must compensate for the missing schema descriptions, it fails to add any meaning beyond the bare parameter name.

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

Purpose5/5

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

The description clearly states the tool lists recently added books from the Calibre library. The verb 'list' and specific resource 'recently added books' provide a distinct purpose that differentiates it from sibling tools like search or details.

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?

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention that if a specific book is needed, calibre_search_books should be used instead. The description only states what it does, without context or exclusions.

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

calibre_run_index_maintenanceA

Start the optional remote maintenance script that refreshes Calibre FTS.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

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

With no annotations provided, the description must fully disclose behavioral traits. It states the effect (refreshes FTS) but omits critical details: whether the operation is safe (read-only vs. destructive), if it requires specific permissions, if it is synchronous or background, or if it can be run concurrently. The verb 'Start' hints at a possible long-running process, but this is not clarified.

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 sentence of 10 words, front-loaded with the verb 'Start'. Every word earns its place, and there is no redundancy or filler. It is optimally concise for the complexity of the tool.

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

Completeness4/5

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

For a simple, parameterless tool with an output schema, the description is largely sufficient. It covers the primary action and effect. However, adding context about the asynchronous nature or the 'remote' aspect could improve completeness, but the output schema likely provides return details, so no major gap.

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

Parameters4/5

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

The input schema has zero parameters, so schema description coverage is 100% trivially. Per the rubric, zero-parameter tools receive a baseline of 4. The description adds no parameter information because none is needed; the action is self-contained.

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

Purpose5/5

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

The description clearly states the tool starts an optional remote maintenance script that refreshes Calibre FTS. It uses a specific verb ('Start') and resource ('remote maintenance script'), and the action ('refreshes Calibre FTS') distinguishes it from sibling tools like calibre_book_details or calibre_search_books, which focus on retrieval or search.

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

Usage Guidelines3/5

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

The description implies usage by calling the script 'optional', suggesting it is not required for normal operation. However, it does not provide explicit guidance on when to use this tool versus alternatives like calibre_index_status (for checking index health) or calibre_index_summary. No prerequisites or contextual triggers are mentioned.

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

calibre_search_booksC

Search Calibre metadata by book title or author.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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

No annotations provided, so description must carry burden. Only says 'Search', but does not disclose case-sensitivity, partial matching, side effects, or response behavior. Minimal transparency.

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

Conciseness4/5

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

One sentence with no filler. Appropriate length for a simple search tool.

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?

For a search tool with an output schema, description does not clarify query format (exact vs fuzzy), limit behavior, or constraints. Given 2 parameters and no schema descriptions, more detail is needed.

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

Parameters2/5

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

Description partially explains 'query' as search term for title/author. Does not explain 'limit' parameter, and schema descriptions are missing. With 0% schema coverage, description should compensate more.

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?

Clearly states the action 'Search' and the target 'Calibre metadata' with criteria 'by book title or author'. Lacks differentiation from sibling 'calibre_search_text' which might search full text, but purpose is still clear.

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?

No guidance on when to use this tool versus alternatives like 'calibre_search_text' or 'calibre_recent_books'. No mention of prerequisites or exclusions.

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

calibre_search_textC

Search extracted full text from indexed Calibre books and return snippets.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
snippet_charsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries full burden. It does not disclose whether search is case-sensitive, supports operators, or any performance/rate limitations. No mention of index requirements or result behavior beyond 'snippets'.

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

Conciseness4/5

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

Single sentence, concise and front-loaded with verb and resource. Could be slightly more informative without losing conciseness, but no wasted words.

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?

Insufficient for a 3-parameter tool with no annotations and no schema descriptions. Fails to explain snippet format, search syntax, or relationship to other index tools. Expected more detail given the complexity.

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

Parameters2/5

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

Schema description coverage is 0%, so description must compensate. It only implies 'query' but does not explain 'limit' or 'snippet_chars' beyond defaults. No clarification of what snippet_chars controls (character count around match).

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

Purpose5/5

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

The description uses a specific verb ('Search') and resource ('extracted full text from indexed Calibre books') and clearly states the outcome ('return snippets'). It effectively distinguishes from siblings like 'calibre_search_books' which likely searches metadata.

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?

No guidance on when to use this tool vs alternatives such as 'calibre_search_books' or prerequisites like needing an index (hinted by 'calibre_index_status' sibling). The description lacks context for appropriate usage.

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. Dates show when Glama detected each change.

  1. 7 tool updatesv0.1.0
    • First observedcalibre_book_details
    • First observedcalibre_index_status
    • First observedcalibre_index_summary
    • First observedcalibre_recent_books
    • First observedcalibre_run_index_maintenance
    • First observedcalibre_search_books
    • First observedcalibre_search_text

TDQS

A3.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: book details, two index reporting tools (status vs. summary), recent books, index maintenance, and two search tools (metadata vs. full text). No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'calibre_verb_noun' pattern using snake_case, making the naming predictable and easy to understand.

Tool Count5/5

With 7 tools, the server is well-scoped for querying and maintaining a Calibre library. It's not overburdened with unnecessary tools nor lacking essential ones for its purpose.

Completeness4/5

The tool set covers core operations: getting book details, searching, listing recent books, and index maintenance. Missing a tool to list all books or filter by other criteria, but given the focus on search and indexing, this is a minor gap.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    D
    maintenance
    An MCP server for managing local Calibre libraries using the calibredb CLI. It allows users to search books, manage metadata, and retrieve EPUB file paths through natural language commands.
    7
    -
  • A
    license
    A
    quality
    C
    maintenance
    An MCP server to manage and organize a Calibre ebook library, enabling metadata editing, search, conversion, and more through AI assistants.
    17
    5
    MIT
  • 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.
    8
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/halimchaibi/calibre-library-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server