bookorbit-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bookorbit-mcp Find 'The Hobbit' and list its chapters."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Structure before text —
list_chaptersreturns chapter labels and sizes, never the body.Bounded, paginated text —
get_chaptercaps output (~24k chars) and pages through long chapters withoffset/nextOffset.Snippet-only search —
search_in_bookreturns 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 |
| Find books by title/author/series; returns |
| Full metadata (description, series, genres, files). |
| Chapter list with per-chapter char/word counts (no text). Parses + caches on first call. |
| Plain text of one chapter, paginated. |
| Keyword search within a book → snippets + locations. |
Discovery & browse
Tool | What it does |
|
|
| Library's series with book/read counts. |
| Books in a series, in order. |
| Library's authors with book counts. |
| One author, including their bio. |
| Books by an author. |
| User collections, one collection's detail, and its books. |
| Saved dynamic filters and the books they match. |
| Libraries with per-library book/size/format stats. |
| Typeahead over authors/series/genres/tags/publishers/languages/narrators/collections — resolve an exact name. |
| A curated shelf: recently-added, want-to-read, up-next-in-series, continue-reading/listening, random, smart-scope. |
| External provider author-bio candidates (enrichment, not your library). |
Reading state & stats
Tool | What it does |
| Per-file progress (+ audiobook progress) for a book. |
| Books you're reading now, with progress. |
| Reading-session history + aggregate stats for a book. |
| Library-wide totals (books/authors/series/storage/…). |
| Your personal reading totals (started/completed/…). |
| One library-wide chart: distributions, top-authors/series, timelines, metadata-health gauges. |
| One personal reading chart: peak-hours, favorite-days, heatmap, completion-latency, goal-trajectory, … |
| One "headline card": reading-streak, reading-goal, year-projection, neglected-gems, library-overview, … |
Annotations (your own highlights & notes)
Tool | What it does |
| All highlights/notes across the library, paginated. |
| Which books have annotations, with counts. |
| One book's highlights/notes, in chapter order. |
Images (returned as image content, not text)
Tool | What it does |
| A book's cover image ( |
| An author's photo ( |
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_TOKENis 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 |
| yes | Base URL, e.g. |
| recommended | Enables automatic token refresh. |
| recommended | |
| alternative | Static Bearer token; dev/testing only (expires ~15 min). |
| optional | Where extracted text is cached (default |
Install & build
npm install
npm run buildUse 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 protocolDesign notes
Chapters follow the TOC, not raw files. A single EPUB spine file can bundle many chapters separated by
#fragmentanchors; 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) andtext/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 toolsget_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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Project Gutenberg: 78,000+ public-domain ebooks with full plain-text retrieval.
Read-only MCP server exposing a user ORANO library to their own AI agent.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Related MCP Servers
- AlicenseBqualityBmaintenanceA local MCP server that gives Claude a durable reading room for EPUB and plain text books, enabling chunk-by-chunk navigation, annotations, progress tracking, and shared margin cards.26122MIT
- AlicenseNot gradedqualityDmaintenanceMCP server enabling LLMs to query a local Calibre Content Server for ebook metadata, chapters, and content in HTML or Markdown.11 npmMIT
- AlicenseBqualityDmaintenanceA local MCP server that lets LLM agents read EPUB books and PDF documents with outline-first navigation, precise node reads, and local SQLite persistence.292MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that gives AI agents access to the world's public domain library. Search, read, and navigate books and audiobooks from Project Gutenberg and LibriVox.MIT