Skip to main content
Glama

bookorbit-mcp

An MCP server that exposes the text of your ebooks — managed by BookOrbit — to LLMs, so an assistant can answer questions about what happens inside a book without you copy-pasting chapters.

It is deliberately navigation-first: instead of dumping a whole 100k-word book into the model's context (which would overwhelm it), the server lets the model find a book, look at its chapter list, and pull only the pieces it needs.

How it works

BookOrbit stores raw EPUB files and exposes a reader backend (/epub/{bookId}/info + /epub/{bookId}/file/{path}). This server uses that backend to read a book's structure, fetch only the needed chapters, strip the XHTML to plain text, and cache the result on disk. Nothing is re-downloaded after the first read.

Three guardrails keep the model from drowning:

  1. Structure before text — list_chapters returns chapter labels and sizes, never the body.

  2. Bounded, paginated text — get_chapter caps output (~24k chars) and pages through long chapters with offset / nextOffset.

  3. Snippet-only search — search_in_book returns short snippets plus a chapter index + offset the model can re-fetch precisely.

Related MCP server: access-calibre

Tools

All tools are read-only.

Find & read book text

Tool

What it does

search_books(query, limit?)

Find books by title/author/series; returns bookId + formats + hasEpub.

get_book(bookId)

Full metadata (description, series, genres, files).

list_chapters(bookId)

Chapter list with per-chapter char/word counts (no text). Parses + caches on first call.

get_chapter(bookId, chapter, offset?, maxChars?)

Plain text of one chapter, paginated.

search_in_book(bookId, query, maxResults?, caseSensitive?)

Keyword search within a book → snippets + locations.

Discovery & browse

Tool

What it does

get_related_books(bookId, kind)

similar / same_series / same_author books for a book.

list_series(page?, size?)

Library's series with book/read counts.

get_series_books(seriesId, page?, size?)

Books in a series, in order.

list_authors(page?, size?)

Library's authors with book counts.

get_author(authorId)

One author, including their bio.

get_author_books(authorId, page?, size?)

Books by an author.

list_collections() / get_collection(id) / get_collection_books(…)

User collections, one collection's detail, and its books.

list_smart_scopes() / get_smart_scope_books(…)

Saved dynamic filters and the books they match.

list_libraries()

Libraries with per-library book/size/format stats.

suggest_metadata(kind, q)

Typeahead over authors/series/genres/tags/publishers/languages/narrators/collections — resolve an exact name.

get_book_shelf(type, limit?)

A curated shelf: recently-added, want-to-read, up-next-in-series, continue-reading/listening, random, smart-scope.

search_author_metadata(q, …)

External provider author-bio candidates (enrichment, not your library).

Reading state & stats

Tool

What it does

get_reading_progress(bookId)

Per-file progress (+ audiobook progress) for a book.

list_currently_reading()

Books you're reading now, with progress.

get_reading_sessions(bookId, page?, …)

Reading-session history + aggregate stats for a book.

get_library_stats()

Library-wide totals (books/authors/series/storage/…).

get_reading_stats()

Your personal reading totals (started/completed/…).

get_library_statistic(kind, libraryIds?)

One library-wide chart: distributions, top-authors/series, timelines, metadata-health gauges.

get_reading_statistic(kind, days?, …)

One personal reading chart: peak-hours, favorite-days, heatmap, completion-latency, goal-trajectory, …

get_dashboard_widget(kind)

One "headline card": reading-streak, reading-goal, year-projection, neglected-gems, library-overview, …

Annotations (your own highlights & notes)

Tool

What it does

list_annotations(page?, pageSize?, bookId?)

All highlights/notes across the library, paginated.

list_annotated_books()

Which books have annotations, with counts.

get_annotations(bookId)

One book's highlights/notes, in chapter order.

Images (returned as image content, not text)

Tool

What it does

get_book_cover(bookId, size?)

A book's cover image (full or thumbnail).

get_author_image(authorId, size?)

An author's photo (full or thumbnail).

Typical flow: search_books → list_chapters → get_chapter / search_in_book.

Requirements & scope

  • EPUB only (v1). Books without an EPUB file return a clear error from the text tools.

  • Auth: BookOrbit access tokens expire after ~15 minutes and there is no long-lived API key, so the server logs in with your username + password and refreshes / re-logs in automatically. A static BOOKORBIT_TOKEN is supported for quick tests but will not auto-refresh.

  • Single-user / local: it acts as the account you configure.

Configuration

Set these as environment variables (or in a local .env — see .env.example):

Variable

Required

Notes

BOOKORBIT_URL

yes

Base URL, e.g. https://bookorbit.example.com (trailing slash ok).

BOOKORBIT_USERNAME

recommended

Enables automatic token refresh.

BOOKORBIT_PASSWORD

recommended

BOOKORBIT_TOKEN

alternative

Static Bearer token; dev/testing only (expires ~15 min).

CACHE_DIR

optional

Where extracted text is cached (default ~/.cache/bookorbit-mcp).

Install & build

npm install
npm run build

Use with a Claude client

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or claude mcp add). Point at the built entry and pass your credentials:

{
  "mcpServers": {
    "bookorbit": {
      "command": "node",
      "args": ["/absolute/path/to/bookorbit-mcp/dist/server.js"],
      "env": {
        "BOOKORBIT_URL": "https://bookorbit.example.com",
        "BOOKORBIT_USERNAME": "your-username",
        "BOOKORBIT_PASSWORD": "your-password"
      }
    }
  }
}

Development

npm test          # unit tests (offline; run against captured fixtures)
npm run typecheck # type-check only
npm run dev       # run the server from source over stdio

# Live checks against a real server (need .env with credentials):
node --import tsx scripts/smoke.mts      # exercises search → parse → chapter → search
node --import tsx scripts/mcp-check.mts   # drives the built server over the MCP stdio protocol

Design notes

  • Chapters follow the TOC, not raw files. A single EPUB spine file can bundle many chapters separated by #fragment anchors; the server resolves the table of contents into meaningful sections and slices each one by its anchor range.

  • Cache layout: ~/.cache/bookorbit-mcp/<bookId>/book.json (chapter list + sizes) and text/section-NNN.txt (extracted text per chapter).

  • Discovery, reading-state, stats, and annotation tools are live passthroughs to BookOrbit and are not cached (that data is mutable); only extracted EPUB text is cached.

  • Not included (v1): semantic/RAG search, cross-library content search, PDF/MOBI, and any write operations. The cache layout leaves room to add a cross-book index later.

Available Tools

33 tools
get_annotationsGet a book's annotationsA

Return the user's own annotations (highlights and notes) for one book by bookId, ordered by the book's chapters. Each includes the highlighted text, any note, and the book's own chapterTitle/chapterIndex. NOTE: chapterIndex is BookOrbit's own chapter numbering, NOT the index used by list_chapters/get_chapter — match on chapterTitle if you want to read the surrounding text.

Inputs: bookId (required).

get_authorGet author detailsA

Get one author by authorId (from list_authors), including their biography (description) and book count. Use get_author_books for their books.

Inputs: authorId (required).

get_author_booksGet an author's booksA

List the books by one author by authorId (from list_authors), paginated. Each item includes series info and whether it has an EPUB.

Inputs: authorId (required), page, size.

get_author_imageGet author imageA

Get an author's photo bytes (returned as an image, not text). Use size 'thumbnail' for a small image or 'full' for the full-size photo. Errors if the author has no image.

Inputs: authorId (required), size.

get_bookGet book detailsA

Get full metadata for one book by bookId, including its files and formats. Use to confirm an EPUB is available and to read the description/series info.

Inputs: bookId (required).

get_book_coverGet book cover imageA

Get a book's cover image bytes (returned as an image, not text). Use size 'thumbnail' for a small image or 'full' for the full-size cover. Errors if the book has no cover.

Inputs: bookId (required), size.

get_book_shelfGet a book shelfA

Get a curated shelf of books (full book cards) by 'type': recently-added, continue-reading, continue-listening (audiobooks), want-to-read, up-next-in-series, random, or smart-scope. Use this to surface reading suggestions and lists no other browse tool reaches. 'smart-scope' requires a smartScopeId (from list_smart_scopes).

Inputs: type (required), limit, smartScopeId.

get_chapterGet chapter textA

Return the plain text of one chapter/section by its index (from list_chapters). Output is capped (default ~24000 chars); if the chapter is longer, use offset with the returned nextOffset to page through it. Read only what you need.

Inputs: bookId (required), chapter (required), offset, maxChars.

get_collectionGet collection detailA

Get one collection's detail (name, description, icon, book count) by collectionId. Companion to get_collection_books; use list_collections to find the id.

Inputs: collectionId (required).

get_collection_booksGet books in a collectionA

List the books in one collection by collectionId (from list_collections), paginated. Optionally filter with q or collapse series into a single entry.

Inputs: collectionId (required), q, page, size, +1 more.

get_dashboard_widgetGet a dashboard widgetA

Get one pre-computed dashboard 'headline card' — the compact, at-a-glance sibling of the richer get_reading_statistic charts. Pick a 'kind':

  • Goals & momentum: reading-streak, reading-goal, year-projection, monthly-challenge.

  • Reading profile: reading-rhythm (14-day series), reading-dna, diversity-score.

  • Nudges / recommendations: neglected-gems (highly-rated but unread), long-wait (longest-unread), highlight-of-the-day (one of the user's own annotations).

  • Overview: library-overview (aggregate totals across all libraries). (For the 'currently reading' card use list_currently_reading.)

Inputs: kind (required).

get_library_statisticGet a library statisticA

Get one pre-aggregated, library-wide statistics chart (not the user's personal reading — use get_reading_statistic for that; for headline totals use get_library_stats). Pick a 'kind':

  • Distributions: format-distribution, genre-distribution, language-distribution, publication-decade, page-count-distribution, storage-by-format.

  • Top-N & rankings: top-authors, top-series, largest-books.

  • Timelines: books-added-over-time, publication-year-timeline, format-share-over-time.

  • Relationships: genre-cooccurrence, acquisition-lag-scatter.

  • Metadata health: metadata-completeness, library-metadata-completeness, metadata-score-distribution, metadata-freshness-gauge, library-integrity-gauge. Optionally restrict to one or more libraryIds. 'granularity' and 'range' apply only to books-added-over-time.

Inputs: kind (required), range, libraryIds, granularity.

get_library_statsGet library statisticsA

Get library-wide totals: number of books, authors, series, publishers, genres, languages, total storage, the publication-year range, and books added this year.

Inputs: no named parameters.

get_reading_progressGet reading progressA

Get the user's reading progress for one book by bookId: per-file percentage and position (and audiobook progress when present). Use to answer 'where am I in this book'.

Inputs: bookId (required).

get_reading_sessionsGet reading sessionsA

Get the user's reading-session history for one book by bookId, paginated, plus aggregate stats (total sessions, total/average time, first/last session, pace).

Inputs: bookId (required), page, pageSize.

get_reading_statisticGet a reading statisticA

Get one pre-aggregated chart of the signed-in user's personal reading activity (derived from reading sessions + progress; for library-wide analytics use get_library_statistic). Pick a 'kind':

  • Activity over time: daily-reading, reading-heatmap, completion-timeline.

  • When they read: peak-hours (by hour), favorite-days (by weekday), session-timeline (one ISO week), session-archetypes.

  • Pace & finishing: reading-pace, completion-latency, completion-race, reading-survival, progress-funnel, goal-trajectory.

  • Breakdowns: genre-reading-time, author-genre-chord, reading-source-distribution. Optionally restrict to libraryIds. 'days' is a trailing look-back window (ignored by session-timeline). Per-kind extras: year/week (session-timeline), comparePrevious (progress-funnel), goalBooks (goal-trajectory).

Inputs: kind (required), days, week, year, +3 more.

get_reading_statsGet reading statisticsA

Get the user's personal reading totals: tracked, started, in-progress, and completed book counts, plus mean progress percent.

Inputs: no named parameters.

get_series_booksGet books in a seriesA

List the books in one series by seriesId (from list_series), in series order, paginated. Each item includes its series index and whether it has an EPUB.

Inputs: seriesId (required), page, size.

get_smart_scope_booksGet books in a smart scopeA

List the books matched by one smart scope by scopeId (from list_smart_scopes), paginated. Optionally filter with q.

Inputs: scopeId (required), q, page, size.

list_annotated_booksList annotated booksA

List the books the user has annotated (highlighted / added notes to), each with an annotation count. Use this to discover which books have annotations before pulling them with get_annotations — like search_books precedes reading.

Inputs: no named parameters.

list_annotationsList all annotationsA

List ALL of the user's annotations (their highlights and notes) across the whole library, newest-page first. Each item includes the highlighted text, any note, the book title/author, and the book's own chapter title/index. Paginated: use page with the returned total/pageSize to browse, or pass bookId to filter to one book. Returns a stats summary (book count, how many have notes, and where they came from).

Inputs: page, bookId, pageSize.

list_authorsList authorsA

List the library's authors (paginated) with their book counts. Use the returned author id with get_author for a bio or get_author_books for their books.

Inputs: page, size.

list_chaptersList chaptersA

List a book's chapters/sections with their sizes (character and word counts) but NO text. Parses and caches the EPUB on first call. Use this to see the book's structure and pick which chapter to read with get_chapter. EPUB only.

Inputs: bookId (required).

list_collectionsList collectionsA

List the user's collections (curated shelves). Use a returned collection id with get_collection_books to read the books it contains.

Inputs: no named parameters.

list_currently_readingList currently readingA

List the books the user is currently reading, each with progress. Use to answer 'what am I reading right now'.

Inputs: no named parameters.

list_librariesList librariesA

List the libraries in the BookOrbit instance with each library's book count, total size, and per-format counts.

Inputs: no named parameters.

list_seriesList seriesA

List the library's series (paginated), each with book/read counts and its authors. Use the returned series id with get_series_books to read the books in a series.

Inputs: page, size.

list_smart_scopesList smart scopesA

List the user's smart scopes (saved dynamic filters). Use a returned scope id with get_smart_scope_books to read the books it currently matches.

Inputs: no named parameters.

search_author_metadataSearch external author metadataA

Search external metadata providers for author-biography candidates by name. This is EXTERNAL enrichment data (bios, images, provider ids) — NOT your library's authors (use search_books / list_authors for those). Useful for 'tell me about this author'.

Inputs: q (required), limit, region, providers.

search_booksSearch booksA

Search the BookOrbit library by title, author, or series. Returns matching books with their bookId and available formats. Use this first to find the book (and confirm it has an EPUB) before reading its text.

Inputs: query (required), limit.

search_in_bookSearch within a bookA

Keyword search inside one book's text. Returns short snippets with the chapter index, character offset, and approximate position (percent through the book). Use the returned chapter + offset with get_chapter to read the surrounding text.

Inputs: query (required), bookId (required), maxResults, caseSensitive.

suggest_metadataSuggest metadata values (typeahead)A

Typeahead lookup over the library's metadata facets — use it to resolve the exact spelling of a name before browsing/filtering (e.g. find the real author or series name to feed elsewhere). Pick a 'kind': authors, series, publishers, languages, narrators, or the user's own collections (each returns { name }), or genres / tags (which also return a filterable { id, name }). Matching is a case- and accent-insensitive 'contains' match on 'q', capped at ~15 results (20 for collections). 'q' is required — an empty/whitespace 'q' returns [].

Inputs: q (required), kind (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but several groups share similar names (progress/sessions/stats, stats/statistic/dashboard, list/get annotations) which could cause misselection. The detailed descriptions mostly mitigate this, but the naming similarity is noticeable.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_*, get_*, search_*, suggest_*). No mixed conventions or irregular verbs are present, making the naming highly predictable.

    Tool Count2/5

    With 33 tools, the set is well over the 25+ threshold for 'too many'. Even though the domain is broad, the count feels inflated, especially with many overlapping analytics-style tools that could potentially be consolidated.

    Completeness4/5

    The read-only domain is well covered: search, browse, read chapters, track progress, annotations, collections, and analytics. Minor gaps include no generic 'list all books' without a query and no per-library detail tool, but these are workable.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers