Readest MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Readest MCP
A small, read-only MCP server for exploring your Readest books and annotations. Search EPUB/PDF text, highlights and personal notes, then retrieve passages with book, chapter/page and revision references. Your assistant uses that evidence to answer questions.
Choose Readest Cloud or a saved local Readest library. Both expose the same six tools and result schemas. This is an unofficial integration, built with the official TypeScript MCP SDK.
Built for my own reading and research, and shared in the hope that others find it useful. Provided as is; development follows my personal needs and available time. Thoughtful bug reports, fixes and contributions are welcome.
Install
Requires Node 24.15+ in the 24 LTS line (including SQLite FTS5).
git clone https://github.com/gbettineschi/readest-mcp.git
cd readest-mcp
npm ci
npm run buildTo use keyword search without the optional local embedding runtime, install with npm ci --omit=optional. GitHub releases also provide a compiled npm package (.tgz) and SHA-256 checksums. Install a downloaded package with npm install ./readest-mcp-0.1.1.tgz, then use npx readest-mcp in that directory. Node 24 and runtime dependencies are still required; model files and Tesseract are installed separately. No npm registry package or standalone binary installer is published.
Related MCP server: AI Knowledge Base MCP Server
Configure
Create a private configuration directory, then save one of these as ~/.config/readest-mcp/config.json. On macOS/Linux:
mkdir -p ~/.config/readest-mcp
chmod 700 ~/.config/readest-mcpOn Windows, create the same directory under your user profile with access limited to your account.
Readest Cloud
{"source":"cloud"}Sign in from your own terminal:
node dist/cli.js loginThe password prompt is hidden. Only a renewable account session is stored, in a private local file; passwords are not stored. Read-only describes this server's allowed operations; the credential is an ordinary Readest account session. Social-only accounts may need a password set in Readest first. This uses Readest's published sync interface and the account flow documented for KOReader, rather than a separate developer API. Cloud storage access still depends on what is uploaded and accessible to your account.
Local library, including Readest-managed Drive sync
{"source":"local","library_dir":"/absolute/path/to/Readest/Books"}Use the directory containing library.json. Omit library_dir only if one saved library exists in a standard app location. For imported files stored elsewhere, add their parent directories as content_roots. The adapter reads saved files passively: download/sync missing books in Readest itself. It does not connect directly to Drive or launch Readest.
Verification note: The local adapter has automated fixture tests, but has not yet been verified end to end with a real local Readest library, including one synced through Google Drive. macOS denied access to Readest's app data on the test machine. See the verification record.
Optional shared settings: cache_dir and embeddings: {"enabled":true,"model_dir":"/absolute/path/to/models"}. Relative paths resolve beside the configuration file; ~ is supported. Keep cache and model directories outside your source content roots. Defaults live under ~/.cache/readest-mcp.
Prepare and connect
node dist/cli.js doctor
node dist/cli.js refresh --content availablerefresh --content all also acquires cloud books where available. --rebuild re-extracts available files and rebuilds generated search data, including retrying OCR after installing missing language data. Neither edits your Readest library. Startup refreshes metadata, not every book's contents; explicit refresh builds the searchable corpus. Reading one book can prepare it on demand.
For Codex, add this to ~/.codex/config.toml, using absolute paths:
[mcp_servers.readest]
command = "/absolute/path/to/node24"
args = ["/absolute/path/to/readest-mcp/dist/cli.js", "serve", "--config", "/absolute/path/to/config.json"]
startup_timeout_sec = 30
tool_timeout_sec = 120Other stdio MCP clients use the same command and arguments. Reconnect the client after changing configuration or signing into a different account. See Codex MCP configuration.
Tools
Tool | Purpose |
| Availability, indexing counts and capabilities |
| Browse/filter known books and saved reading state |
| Book details and available chapter/page structure |
| Highlights, comments, bookmarks, excerpts, notebook and ink records |
| Keyword, semantic or hybrid search; select text, quotes or notes |
| Read a passage, chapter/page or annotation; follow continuation cursors |
Results use data, status, warnings, error and meta in both modes. Metadata reports source, refresh time, cached fallback and known coverage. Normal pagination is not a failure; ok does not promise an exhaustive personal library or conceptual search. Quotes and your comments remain separate. References belong to the indexed revision and become stale after an edition change.
Try asking your assistant:
“List books tagged research and show my notes on one of them.”
“Search book text for uncertainty; read the matching passages and cite their chapters.”
“Use hybrid search to find discussions of deciding with incomplete information. Distinguish my comments from the author's text.”
Optional semantic search
Set embeddings.enabled to true, then run:
node dist/cli.js models fetch
node dist/cli.js refresh --content availableThis explicitly downloads about 135 MB of pinned, checksum-verified multilingual MiniLM model files. Inference runs locally on CPU; book text is not uploaded to an embedding service. For semantics, adjacent EPUB paragraphs in the same section form continuous documents, so headings have surrounding context. These are split within the model's 128-token budget; keep queries concise. Search returns a retrievable reference to the matching window with source offsets. Original paragraphs remain available to keyword search and reading; PDF pages and annotations stay separate. Hybrid fuses the two channels at the section identity. If semantics is unavailable, semantic requests fail clearly and hybrid reports a keyword fallback. After a model/index update, run models fetch and refresh again; old vectors are isolated by manifest identity.
Optional PDF OCR
PDF pages with embedded text are read directly. Pages with no drawing operations are treated as blank. For image-only pages, optionally install Tesseract and the language data you need, then add:
{"ocr":{"enabled":true,"command":"/absolute/path/to/tesseract","languages":["eng","ita"]}}OCR runs locally, without modifying the PDF or uploading page images. It requires the optional canvas dependency included by a normal npm ci. Recognized passages carry text_origin: "ocr" and an accuracy warning. Missing tools, language data and unrecognized pages retain explicit gaps. Changed settings mark cached PDF extraction as stale on startup; search may use it with cache/incomplete-coverage warnings until refreshed. On-demand reads re-extract it and reject expired references. Native text is extracted first; optional rendering and recognition share a bounded deadline. Per book, OCR is limited to 8 pages and up to 30 seconds of the remaining 60-second extraction budget; extensive scans should be OCR-processed separately. Only pages without embedded text are candidates, so this does not detect missing text within an otherwise text-bearing page.
Limits and verification
EPUB 2/3 and text-bearing PDFs are supported, with bounded optional OCR as above. Encrypted PDFs, extraction gaps and missing files are reported. PDF layout extraction is imperfect. Original annotation locators are preserved; quote context may be ambiguous or unresolved. Ink strokes are retained where available, without handwriting recognition. Large annotation payloads may be explicitly truncated.
Pages default to 20 items (maximum 50); excerpts to 320 characters; content to 4,000 (maximum 12,000, with continuation). Responses are bounded at 64 KiB. Files are limited to 256 MiB, expanded EPUBs to 512 MiB/20,000 entries, extraction to 60 seconds.
Synthetic local/cloud tests exercise all six tools through real MCP processes, plus package installation and exact-reference retrieval. A small real-model test checks English/Italian paraphrases; it is not a quality benchmark. Compatibility evidence distinguishes fixture, live-account and client checks. Cloud compatibility follows a pinned Readest implementation and may need adjustment as Readest evolves.
npm run typecheck
npm test
READEST_TEST_MODEL=1 npm test -- tests/semantic-model.test.ts
READEST_TEST_OCR=1 npm test -- tests/content.test.ts
# Opt in only with your private source configured:
READEST_TEST_LIVE=1 npm test -- tests/live.test.tsMIT for original code. See third-party notices and contribution notes.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and read the articles, videos, podcasts, PDFs and notes you saved in Recall. Read-only.
Search and organize your reading library of highlights, saved articles, notes and tags.
Search a catalog of 1.7 million books and find books by mood, vibe, pace or genre. Read-only.
Search and read Cyber Library, a free structured cybersecurity knowledge base. Read-only, no auth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables read-only access to local Calibre libraries for searching metadata, inspecting book formats, and extracting content samples. Supports full-text search, batch operations, and detailed book analysis through natural language queries.3MIT
- AlicenseBqualityCmaintenanceProvides read-only hybrid RAG search and discovery over a local-first AI knowledge corpus, enabling semantic and keyword search, browse, digest, and status tools.41PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query a local reader's current state (book, chapter, CFI, visible text, selection) and perform actions like opening books, navigating by CFI or progress, searching, and creating or clearing highlights.MIT
- AlicenseNot gradedqualityBmaintenanceProvides read-only search and context-pack creation over a local source library, letting AI assistants retrieve relevant excerpts and audit cited quotations.20MIT