ebook-translator-mcp
An MCP server that lets any AI agent read and write the Calibre Ebook Translator plugin's local SQLite translation cache, chunk by chunk, replacing manual copy-paste.
Discover caches:
list_bookslists every cached book (including temporary caches) with engine, languages, progress and non-aligned count; flags duplicate titles and supports keyword filtering.Inspect a book:
get_book_inforeturns engine, target language, merge/alignment rules, progress and the ids of non-aligned (yellow) chunks.Survey chunks cheaply:
list_chunksgives a per-chunk status table without full texts, filterable byall/untranslated/translated/misalignedor keyword.Read content:
get_originalreturns a chunk's original text (as shown in the proofreading panel) andget_translationreturns its translation plus the alignment verdict.Bulk text without token cost:
get_original_to_file/get_translation_to_fileexport text to local files (metadata only), andwrite_chunk_from_filewrites a translation back from a local.txtfile — no truncation or hallucination risk on large chunks.Write and verify:
write_chunkstores a translation, replicates the plugin's yellow-highlight alignment check, and reads the stored text back to confirm the write.Rework:
delete_translationsclears translations of given chunks (originals untouched) so individual rows can be redone without renumbering others.Safe operation: only existing caches are touched, writes are short retrying transactions safe while Calibre is open, SQL is parameterized and
book_idcannot escape the cache directory.Addressing discipline: results echo
book_id+ title; chunks are addressed by stablebook_id+chunk_id, never byui_row.Flexible deployment: stdio for Claude Desktop/Code, Cursor, Cline, dsh, or HTTP mode for a remote Calibre machine.
Reads and writes the SQLite translation-cache files produced by the Calibre Ebook Translator plugin. Exposes tools to list cached books, inspect per-chunk status and alignment, read a chunk's original text or current translation (inline or exported to a local file), write or replace a chunk's translation (inline or from a local file), and clear translations for rework — with parameterized SQL, short retrying transactions, and book/chunk addressing scoped to each cache file.
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., "@ebook-translator-mcp Translate the untranslated chunks of 'Dune' one by one."
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.
MCP for Calibre Ebook Translator
An MCP server that lets any AI agent (Claude Desktop, Claude Code, Cursor, Cline, dsh, ...) read and write the translation cache of the Calibre Ebook Translator plugin — directly, chunk by chunk, replacing manual copy-paste.
The plugin keeps doing what it is good at (parsing ebooks, splitting text into numbered chunks, merging output). The agent does the translation in your chat window, using any model you like. The book never leaves your machine: everything happens through local SQLite cache files.
How it works
The Ebook Translator plugin stores each book's translation progress in a SQLite cache. This server opens those cache files read/write and exposes ten tools: list books, inspect chunk status, read a chunk's original text, read or write its translation — inline or via local files — and clear translations for rework. Every response echoes the book id and title so the agent (and you) can always verify which book is being touched.
Key properties:
Chunk-addressed: one chunk = one numbered row in the plugin's advanced mode table.
chunk_idis the database row id — it never changes, even if you delete other rows in the UI.Alignment-aware: when the plugin's merged translation is enabled, a translation must split into the same number of blank-line-separated blocks as its original, otherwise the plugin highlights the row yellow. The server replicates this exact check and reports
alignedon every read and write — you know before reopening the plugin whether a row would go yellow.Safe by construction: only existing cache files are touched; writes are short retrying transactions, safe to run while Calibre is open; SQL is fully parameterized and
book_idcannot escape the cache directory.
Related MCP server: Calibre MCP Server
Requirements
Calibre with the Ebook Translator plugin (verified against v2.4.2), with a book already segmented in advanced mode (caching enabled, or the advanced-mode window still open)
Python 3.10+ (from python.org — on Windows, avoid the Microsoft Store stub, see Troubleshooting)
Any MCP client that supports stdio servers
Install
Option A — run directly with uv (no install, no clone):
uvx --from git+https://github.com/riverai/MCP-for-Calibre-Ebook-Translator ebook-translator-mcp --selftestOption B — manual:
pip install mcp
# download ebook_translator_mcp.py, then:
python /path/to/ebook_translator_mcp.py --selftestThe self-test prints the cache directory it detected and every book it can see. If your books show up there, the server will work.
Connect your MCP client
The server name below can be anything; command/args is what matters.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"ebook-translator": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/riverai/MCP-for-Calibre-Ebook-Translator",
"ebook-translator-mcp"
]
}
}
}or, with a local copy and pip install mcp:
{
"mcpServers": {
"ebook-translator": {
"command": "python",
"args": ["C:/tools/MCP-for-Calibre-Ebook-Translator/ebook_translator_mcp.py"]
}
}
}Claude Code:
claude mcp add ebook-translator -- uvx --from git+https://github.com/riverai/MCP-for-Calibre-Ebook-Translator ebook-translator-mcp
# or: claude mcp add ebook-translator -- python /absolute/path/to/ebook_translator_mcp.pyCursor (.cursor/mcp.json or ~/.cursor/mcp.json) and Cline (cline_mcp_settings.json): use the same mcpServers JSON as Claude Desktop.
dsh: see dsh/register.yml — note the toolCallTimeoutMs recommendation there.
Remote (Calibre on another machine): start HTTP mode on that machine, then point any streamable-http client at it:
python ebook_translator_mcp.py --transport http --port 8420
# endpoint: http://<that-machine>:8420/mcpTools
Tool | What it does |
| List every cached book: engine, languages, progress, non-aligned count; |
| One book's engine, target language, merge/alignment rule, progress, and the list of non-aligned chunk ids |
| Lightweight per-chunk status table (no full texts); filter by |
| Full original text of one chunk — exactly what the plugin's proofreading panel shows |
| Export one chunk's original to a local file — returns only metadata; the text itself never enters the conversation |
| Full translation of one chunk plus the alignment verdict ( |
| Export one chunk's current translation to a local file (metadata + alignment only) — for offline rework, human review, or migrating to a new cache |
| Write one chunk's translation; returns alignment state and a |
| Write one chunk's translation from a local |
| Clear translations of the given chunks (for rework); originals untouched |
For large chunks, prefer the file pipeline: get_original_to_file exports the original to a local file, the agent translates against that file, and write_chunk_from_file stores the result — bulk text never passes through the conversation (no token cost, no truncation or hallucination risk). get_translation_to_file closes the rework loop: export a misaligned translation, fix its block count offline, write it back.
Addressing model
book_idis the cache file name, obtained fromlist_books. Every call echoesbook_id+ title — check the echo.Segmenting the same book with a different engine / target language / merge setting creates a separate cache (same title, different id). Duplicate titles are flagged
duplicate_title; disambiguate byengine/target_lang/merge_length.chunk_idis the database row id: stable forever, but valid only inside its own book. One chunk going wrong never renumbers the others — redo just that chunk (delete_translations+write_chunk).ui_rowis the row's display position in the plugin table (for humans to find the row on screen). Never address by it.
Alignment (the yellow highlight)
With merged translation enabled, original and translation must split into the same number of blocks on blank lines (\n\n). If they don't, the plugin highlights the row yellow as "Non-aligned". All read/write tools report:
"alignment": {
"applicable": true,
"aligned": false,
"original_blocks": 17,
"translation_blocks": 16
}So an agent can translate, write, and immediately see whether the row would go yellow — and fix it before you ever open Calibre.
Recommended workflow
list_books→ pick the rightbook_id(watchduplicate_title)get_book_info→ note merge settings and existing non-aligned chunkslist_chunkswithstatus="untranslated"→ pick a chunkget_original→ translate it in the chat (keep the block count if merging is on); orget_original_to_fileto export it to a file and translate against the file (recommended for large chunks)write_chunk(orwrite_chunk_from_filefor large chunks — pass a local file path so the text never passes through the chat) → checkalignment.alignedin the response, and treat a missingverify_mismatchas "write verified"Misaligned? Rewrite the chunk (or
delete_translationsfirst) until aligned — for large chunks:get_translation_to_file+ fix the block count offline +write_chunk_from_fileRepeat until
list_chunkswithstatus="misaligned"comes back emptyHuman step: reopen advanced mode in Calibre with the same engine/language/merge settings, review, then click Output
Important behaviors
Output uses the cache as-is: the plugin's Output step reads whatever translations are in the cache; externally written ones are picked up directly.
No live refresh: the advanced-mode table loads once at open. Writes made while it is open are not shown until you reopen it. Also, clicking Save in the UI while the window is open can overwrite externally written rows with stale in-memory data — close the window while an agent is writing in bulk.
Settings define the cache file: the cache file name is a hash of book + engine + target language + merge setting. Changing any of these mid-project points at a different cache file.
Temporary caches die with the window: if caching is disabled in plugin settings, the cache exists only while the advanced-mode window is open.
Timeouts: "MCP error -32001" but the write actually succeeded
If a write collides with a write lock held by the Calibre UI (any Save/ignore action), the server waits silently — up to ~23s (4 attempts x 5s busy timeout + backoff) — and sends the client nothing meanwhile. Clients whose tool-call timeout is shorter will report -32001: Request timed out first, while the server still completes the write after the lock is released. Two defenses:
Raise the client's tool-call timeout to 60s or more (dsh:
toolCallTimeoutMs: 120000, already set indsh/register.yml).If you ever see -32001: do not blind-retry the write. Call
get_translationfirst to check whether the translation actually landed; rewrite only if it is missing.
Every lock wait is logged to the server's stderr for diagnosis.
Troubleshooting
Symptom | Cause and fix |
| Caching is not enabled in plugin settings (or the advanced-mode window was closed and its temp cache vanished). Segment a book in advanced mode first; or point |
Writes land on the wrong book | Same title, multiple caches. Re-check |
Windows: a black console window flashes and the server never starts | The |
| See the timeouts section — the write probably succeeded; verify with |
Rows show yellow in the plugin | Misaligned chunk: the translation's blank-line block count differs from the original's. Have the agent rewrite that chunk with matching block count |
Environment variables
Variable | Meaning | Default |
| Explicit cache root (highest priority; then the plugin's configured | auto-detect |
| Engine name recorded next to written translations |
|
| Separator used by the alignment check |
|
Related projects
bookfere/Ebook-Translator-Calibre-Plugin — the plugin this server talks to (not affiliated; this is an independent third-party tool)
License
Available Tools
10 toolsdelete_translationsA
Clear the translations of the given chunks (for rework); originals and all other fields are untouched. chunk_ids is a list of this book's database cache ids (never change; see list_chunks; valid only inside this book). A chunk that went wrong only needs its own redo — other chunks are not affected. The response echoes book_id and title; verify them.
Inputs: book_id (required), chunk_ids (required). Returns: object
get_book_infoA
Details of one book's cache: engine, target language, merge / alignment rules, progress, and the list of non-aligned (yellow- highlighted) chunk ids.
Inputs: book_id (required). Returns: object
get_originalA
Read the full original text of one chunk — identical to what the UI's proofreading panel shows, so the agent sees the same text a human sees. chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book — never use it across books). When merged translation is enabled the response includes blocks: the translation's blank-line block count must equal it to be aligned (otherwise the UI highlights the chunk yellow). include_raw=True additionally returns the raw HTML. The response echoes book_id and title — verify it is the intended book.
Inputs: book_id (required), chunk_id (required), include_raw. Returns: object
get_original_to_fileA
Export one chunk's original text to a local file and return only metadata — the text itself never enters the conversation (zero content tokens, no truncation risk on huge chunks). Mirrors get_original (same metadata fields, same stripped text as the UI proofreading panel shows) and is the symmetric counterpart of write_chunk_from_file: originals flow cache -> file, translations flow file -> cache, bulk text never passes through the agent.
Typical use: the first pass of a formal translation workflow — export the original to a file, translate against the file, write the result back with write_chunk_from_file. For ad-hoc inspection prefer get_original directly.
File handling: UTF-8 without BOM, LF line endings. Missing parent directories are created automatically (creating a directory destroys nothing; the resolved path is echoed as exported_file). An existing file is NOT overwritten unless overwrite=True — a mistyped path must never silently destroy an existing file (e.g. a finished translation draft). After writing, the file is read back and verified; verify_mismatch appears only if it differs. Relative paths resolve against the server process's working directory, which may differ from the caller's — absolute paths are strongly recommended. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.
Inputs: book_id (required), chunk_id (required), file_path (required), overwrite. Returns: object
get_translationA
Read the full translation and alignment state of one chunk — identical to what the UI's proofreading panel shows. chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book — never use it across books). translation is null when the chunk is untranslated. When merged translation is enabled the response carries the alignment verdict (whether translation and original have equal blank-line block counts, i.e. whether the UI highlights the row yellow). The response echoes book_id and title — verify it is the intended book.
Inputs: book_id (required), chunk_id (required). Returns: object
get_translation_to_fileA
Export one chunk's current translation to a local file and return only metadata — the text itself never enters the conversation. Mirrors get_translation (same metadata and alignment fields, same stripped text as the UI proofreading panel shows).
Typical uses:
Rework a yellow (misaligned) chunk without any bulk text through the agent: export the translation, fix the block count offline (editor or script — deterministic, zero tokens), write it back with write_chunk_from_file.
Migrate translations after changing engine / target language / merge settings (the plugin then creates a new cache file): export every chunk from the old cache, write them into the new one.
Hand the current draft to a human reviewer, or archive a book's translations as plain text.
The chunk must already have a translation (status translated); exporting an untranslated chunk is an error. File handling is the same as get_original_to_file: UTF-8 without BOM, LF; missing parent directories are created automatically; an existing file is not overwritten unless overwrite=True; the file is read back and verified (verify_mismatch appears only on mismatch). Relative paths resolve against the server process's working directory — absolute paths recommended. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.
Inputs: book_id (required), chunk_id (required), file_path (required), overwrite. Returns: object
list_booksA
List all cached translation books with progress (including temporary caches). The returned id is the book_id used by every other tool. Note: segmenting the same book with different engine / target language / merge settings produces multiple caches (same title, different ids) — duplicate titles are flagged duplicate_title=true; disambiguate by engine/target_lang/merge_length and pick one, since picking the wrong book makes every later read/write land on the wrong cache. keyword fuzzy-filters by title/engine/language (useful when there are many books). persistent=false means a temporary cache (destroyed as soon as the advanced-mode window closes).
Inputs: keyword. Returns: result
list_chunksA
Lightweight list of every chunk id of one book with status, without full texts (to keep context small); mirrors the left-hand table of the UI. status options: all / untranslated / translated / misaligned (the UI's yellow rows); keyword fuzzy-matches original or translation text. Each item contains: chunk_id (for addressing; never changes; valid only inside this book), ui_row (UI display position, human reference only), status, alignment, block count, character count and a one-line preview. Always address chunks as book_id + chunk_id — never use ui_row, and never carry this book's chunk_id over to another book. The response echoes book_id and title so the caller can verify it is working on the intended book.
Inputs: book_id (required), status, keyword. Returns: object
write_chunkA
Write the full translation of one chunk (stripped before writing, matching plugin behavior; engine name and target language are recorded). chunk_id is this book's database cache id (never changes; see list_chunks; valid only inside this book). Right after writing, the tool replicates the UI alignment check and returns the aligned state — mismatched block counts come with a warning (the chunk will be highlighted yellow in the UI), and the stored text is read back and verified (verify_mismatch appears only if it differs). With overwrite=False an existing translation is skipped. The response echoes book_id and title: writing is irreversible, verify it is the intended book first. For very large translations prefer write_chunk_from_file (file-based: zero content tokens, no truncation risk).
Inputs: book_id (required), chunk_id (required), translation (required), overwrite. Returns: object
write_chunk_from_fileA
Write one chunk's translation from a local text (.txt) file — the recommended path for large translations. The agent passes only a file path, never the content: zero token cost for the text and no risk of truncation or mutation in transit. Whatever is in the file is exactly what gets stored (the local file is the source of truth, the cache is the mirror).
File handling: the file must exist and be valid UTF-8. A UTF-8 BOM is stripped automatically; leading/trailing whitespace is stripped exactly like write_chunk; and — with the default LF-based alignment separator — CRLF/CR line endings are normalized to LF (text stored with CRLF could never match an LF separator and every multi-block chunk would be flagged misaligned). If the configured separator itself contains CR, line endings are preserved verbatim instead. Empty or whitespace-only files are rejected. Relative paths resolve against the server process's working directory, which may differ from the caller's — absolute paths are strongly recommended (the resolved path is echoed back as source_file so mismatches are visible).
The response has the same structure as write_chunk (written / characters / alignment / progress / warning), plus source_file. After writing, the stored text is read back and compared inside this tool: if verify_mismatch is present (true), the stored text differs from the file — do not trust the write; inspect with get_translation and retry. overwrite=False skips chunks that already have a translation. chunk_id is this book's database cache id (see list_chunks); the response echoes book_id and title — verify it is the intended book.
Inputs: book_id (required), chunk_id (required), file_path (required), overwrite. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a distinct target, but the set contains deliberate inline/file pairs (write_chunk vs write_chunk_from_file, get_original vs get_original_to_file, get_translation vs get_translation_to_file) that share the same underlying action. The descriptions explicitly differentiate them (token cost, truncation, bulk workflow), so confusion is low, but the overlap is real.
All tools use consistent snake_case verb_noun naming (write_chunk, list_books, get_translation, delete_translations). The _to_file/_from_file variants follow a systematic, predictable suffix convention rather than ad-hoc deviations.
Ten tools is well within a reasonable range for a translation cache workflow. The count is slightly inflated because three actions are offered in both inline and file variants, but each variant earns its place by serving a distinct token-budget scenario.
The surface covers the core lifecycle: list/get books and chunks, read originals and translations (inline and via file), write translations (inline and from file), and delete translations for rework. Gaps are minor — no book creation/deletion or rename, but those are handled by the plugin rather than the agent.
Maintenance
Related MCP Connectors
Read and write your Matryoshka Mind Map (nested mind map / TODO app) from AI agents.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
Shared knowledge cache for AI coding agents — reuse an answer once it exists.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with research capabilities for local Calibre e-book libraries, including fulltext search across titles, ISBNs, and comments, plus structured excerpt retrieval from books.2GPL 3.0
- AlicenseBqualityCmaintenanceConnects AI agents to Calibre ebook libraries for searching, reading, and managing digital collections. It supports metadata updates, format conversion, and full-text content searches while providing granular permission controls for library access.725MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to read and write JSON translation files (i18n, i18next, react-i18next) via the Model Context Protocol.257 npm2-
- AlicenseNot gradedqualityDmaintenanceA low-token human-AI co-reading MCP tool that imports local EPUB/TXT/Markdown books into chunks, enabling AI to read only relevant fragments and write co-reading results to long-term reading notes and progress files.79MIT