Skip to main content
Glama
pastukhov

opds-mcp

by pastukhov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

opds-mcp

CI Coverage

An MCP server that lets an LLM browse, search and download books from OPDS catalogs (Open Publication Distribution System) — the Atom/JSON-based feed format used by digital libraries such as Project Gutenberg, Standard Ebooks, Feedbooks, and many self-hosted book servers (Calibre-Web, COPS, KOReader sync targets, etc).

Supports both OPDS 1.x (Atom + XML) and OPDS 2.0 (JSON) catalogs, OpenSearch-based full-text search, and downloading acquisition links to disk.

Tools

  • opds_browse — fetch a catalog/feed document and return its navigation links (search, next/prev, subsections, facets) plus entries (title, authors, summary, categories, acquisition links, cover images).

  • opds_search — search a catalog. Give it either the catalog's feed URL (its rel="search" link is discovered automatically) or an OpenSearch description URL directly, plus a free-text query.

  • opds_get_entry — fetch a single entry/publication document (e.g. an entry's rel="alternate" link) for full details.

  • opds_download — download the file behind an acquisition link to a local directory and return the saved file path.

All tools accept optional username/password for catalogs that require HTTP Basic Auth. The url argument of opds_browse/opds_search/opds_get_entry is optional if the server is configured with a default catalog via OPDS_BASE_URL (see below) — pass url explicitly to browse a different catalog for that one call.

Related MCP server: access-calibre

Install

npm install
npm run build

Configure in an MCP client

Via npx (no local checkout required)

The package hasn't been published to the npm registry, but npx can install and run it straight from this GitHub repo — it clones the repo, runs npm install (which triggers the prepare script to build dist/), then executes the opds-mcp bin:

{
  "mcpServers": {
    "opds": {
      "command": "npx",
      "args": ["-y", "github:pastukhov/opds-mcp"],
      "env": {
        "OPDS_BASE_URL": "https://example.com/opds/root.xml",
        "OPDS_USERNAME": "optional-default-username",
        "OPDS_PASSWORD": "optional-default-password",
        "OPDS_DOWNLOAD_DIR": "/absolute/path/to/save/books"
      }
    }
  }
}

To pin a specific branch or commit, append it: "github:pastukhov/opds-mcp#branch-or-sha".

Via a local checkout

Example for Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "opds": {
      "command": "npx",
      "args": ["-y", "/absolute/path/to/opds-mcp"],
      "env": {
        "OPDS_BASE_URL": "https://example.com/opds/root.xml",
        "OPDS_USERNAME": "optional-default-username",
        "OPDS_PASSWORD": "optional-default-password",
        "OPDS_DOWNLOAD_DIR": "/absolute/path/to/save/books"
      }
    }
  }
}

npx -y /absolute/path installs dependencies and builds on first run, same as the GitHub form above. Alternatively, run npm install && npm run build yourself and point command/args directly at node and dist/index.js.

  • OPDS_BASE_URL — the catalog opds_browse/opds_search/opds_get_entry use when a tool call doesn't pass its own url. This is the recommended way to point the server at a specific library (e.g. https://your-library.example/opds) without relying on the model to know or guess the address; omit it to require an explicit url on every call instead.

  • OPDS_USERNAME/OPDS_PASSWORD — used as a fallback whenever a tool call doesn't pass its own credentials, which is convenient when the server is dedicated to a single authenticated catalog.

  • OPDS_DOWNLOAD_DIR — where opds_download saves files; defaults to a directory under the OS temp folder.

Example flow

  1. opds_browse with the catalog's root URL to see navigation links and/or a first page of entries.

  2. opds_search with that same root URL and a query to find a specific book.

  3. Pick an entry's acquisitions[].href from the result and pass it to opds_download to save the file locally (or use opds_get_entry first if you need more detail than the search result already includes).

Development

npm run dev            # run the server directly with tsx
npm run typecheck      # tsc --noEmit
npm test               # vitest, using fixture OPDS documents under fixtures/
npm run test:coverage  # vitest with a coverage report under coverage/
npm run build          # compile to dist/

Every pull request runs typecheck, build and test:coverage via .github/workflows/ci.yml. On every push to main, .github/workflows/coverage-badge.yml recomputes coverage and commits .github/badges/coverage.json, which the badge at the top of this file reads via shields.io's endpoint badge.

Notes

  • Only http:/https: URLs are accepted; other schemes are rejected before any request is made.

  • Downloaded files are capped at 200MB by default and written under a sanitized filename inside the configured download directory.

  • Because feed documents can be arbitrarily large, opds_browse/opds_search return whatever a single page contains; use the navigation.next link from the response to page through the rest of the catalog.

Available Tools

4 tools
opds_browseBrowse an OPDS catalogB

Fetches an OPDS catalog document (feed, navigation, or acquisition list; OPDS 1.x Atom/XML or OPDS 2.0 JSON) and returns its navigation links (search, next/prev, subsections) and entries (books/publications) with their acquisition (download) and cover image links.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoAbsolute URL of the OPDS catalog/feed document to fetch. Optional if the server was started with a default catalog URL (OPDS_BASE_URL); required otherwise.
passwordNoHTTP Basic Auth password, if the catalog requires authentication
usernameNoHTTP Basic Auth username, if the catalog requires authentication

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations, the description is the sole source of behavioral info. It explains the output structure (navigation links, entries with links) and the input format (URL, auth). However, it does not disclose error behavior, pagination, rate limits, or side effects. The description adds marginal value beyond what the input schema already conveys.

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?

The description is a single sentence that efficiently conveys the core functionality and output. However, it is somewhat long and could be split for readability. It is not overly verbose, so it earns a 4.

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

Completeness3/5

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

Given the complexity of the tool (no output schema, no annotations, moderate parameter count), the description covers the return values but lacks details on error handling, pagination limits, or authentication failure scenarios. It is sufficient for basic understanding but not fully complete.

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?

Schema description coverage is 100%, so the description does not need to add parameter details. However, it adds no additional context beyond the schema (e.g., clarifying when url is required). The baseline of 3 is appropriate since the schema already explains all three parameters.

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 tool fetches an OPDS catalog document and returns navigation links and entries. It specifies the document types and formats, aligning well with the title. However, it does not explicitly differentiate from sibling tools like opds_search or opds_download, though the purpose is distinct enough given the context.

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, nor does it mention prerequisites, authentication requirements beyond the schema, or scenarios where it should not be used. This lack of usage direction is a significant gap.

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

opds_downloadDownload a publication from an OPDS acquisition linkA

Downloads the file behind an OPDS acquisition link (as returned in the acquisitions array of opds_browse/opds_search/opds_get_entry) to a local directory and returns the saved file path. Defaults to a directory under the OS temp folder (/tmp/opds-mcp-downloads); configure OPDS_DOWNLOAD_DIR to persist elsewhere.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAbsolute URL of the acquisition (download) link
passwordNoHTTP Basic Auth password, if the catalog requires authentication
usernameNoHTTP Basic Auth username, if the catalog requires authentication
suggestedNameNoPreferred base file name (without extension), e.g. the book title

TDQS

A4.1/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. Describes download destination (temp dir or configurable) and return value. Lacks details on failure behavior, overwrite policy, or file extension handling.

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?

Two sentences, front-loaded with main action, no redundancy. Efficiently conveys purpose and configuration option.

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

Completeness5/5

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

Given no output schema, the description clearly states return value (saved file path) and destination. Low-complexity tool is fully specified for agent 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?

Schema coverage is 100% with descriptions for all 4 parameters. Description adds context about URL origin but no parameter-specific guidance beyond schema.

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 it downloads a file from an OPDS acquisition link to a local directory and returns the path. It distinguishes from siblings (opds_browse, opds_search, opds_get_entry) which handle metadata discovery.

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

Usage Guidelines4/5

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

Explicitly specifies when to use: after obtaining an acquisition link from opds_browse/opds_search/opds_get_entry. Does not include exclusions or alternatives, but siblings naturally cover different operations.

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

opds_get_entryGet a single OPDS entry/publicationA

Fetches a single OPDS entry document (a per-publication Atom entry or OPDS 2.0 publication), typically the URL found in an entry's rel="alternate" link, and returns its full details including acquisition links.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoAbsolute URL of the entry/publication document to fetch. Optional if the server was started with a default catalog URL (OPDS_BASE_URL); required otherwise.
passwordNoHTTP Basic Auth password, if the catalog requires authentication
usernameNoHTTP Basic Auth username, if the catalog requires authentication

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description shoulders the transparency burden. It explains what the tool does (fetches and returns details) but omits failure modes, auth error behavior, or read-only nature beyond what's implied.

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, well-structured sentence that front-loads the action ('Fetches') and efficiently conveys key details without wasted words.

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 simplicity of the tool (3 parameters, no output schema), the description adequately covers what is fetched and the typical source of the URL. It could mention error handling but is largely complete for a straightforward fetch.

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?

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides—it essentially repeats the schema's parameter comments.

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 it fetches a single OPDS entry document with full details and acquisition links, distinctly separating it from siblings like opds_browse, opds_download, and opds_search.

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

Usage Guidelines4/5

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

The description mentions the typical use case ('URL found in an entry's rel="alternate" link') but does not explicitly compare with siblings or provide when-not-to-use guidance. Still, context is clear.

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. 4 tool updatesv0.1.0
    • First observedopds_browse
    • First observedopds_download
    • First observedopds_get_entry
    • First observedopds_search
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

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: opds_browse for navigation, opds_search for queries, opds_get_entry for detailed entry info, and opds_download for file retrieval. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent opds_verb_noun pattern (opds_browse, opds_download, opds_get_entry, opds_search), making the set predictable and easy to understand.

Tool Count5/5

With exactly 4 tools, the server covers the essential operations for an OPDS client (browse, search, get entry, download) without being excessive or insufficient.

Completeness5/5

The tool set provides complete coverage for interacting with an OPDS catalog: navigating feeds, searching, retrieving detailed entry information, and downloading files. No obvious gaps for client-side operations.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers