audiobook_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., "@audiobook_mcp start converting my audiobook.mp3 with its EPUB and run until done"
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.
audiobook_mcp
An MCP server that turns a single-file MP3/M4A audiobook plus its EPUB
into a properly chaptered M4B — the audiobook-mp3-to-m4b
skill's pipeline, exposed as MCP tools instead of a script you shell out
to by hand.
Chapter boundaries are found by locating the real silence gap at each
chapter transition and anchoring the search for chapter N+1 on chapter
N's actual detected boundary — not on a bookseller's rounded displayed
durations (which drift over a long book) or on EPUB word-count pacing
alone (dialogue-heavy vs. descriptive passages read at different speeds).
Because that chain starts from chapter 1, an unconfirmed guess at chapter
1's own start (most commonly a missed opening-credits/intro segment) would
otherwise throw off every chapter behind it — so before the chain runs at
all, chapter 1's boundary is confirmed by transcribing candidate gaps near
the start of the file (via whisper.cpp) and checking each against the
EPUB's own chapter-1 text (verify_first_chapter, on by default; falls
back to a silence-only guess if whisper.cpp isn't configured). See
audiobook_mcp/pipeline.py's module docstring for the full rationale,
including how it filters out the short "decoy" gap some publishers place
a few seconds after the real transition.
Why this is a resumable job, not one blocking tool call
A 20+ hour audiobook can take longer to fully process than most MCP
clients will happily block a single tool call for. So conversion is
modeled as a job: audiobook_start_conversion creates it,
audiobook_continue_conversion (fine-grained) or audiobook_run_until_done
(loops internally) advance it in bounded time chunks and checkpoint to
disk after every unit of progress, and audiobook_get_status reads
progress without doing any work. Call continue_conversion/run_until_done
repeatedly until the response's "done" field is true. This is the
same checkpoint-and-resume design the underlying skill uses for the same
reason, generalized from a hard 45-second sandbox cap to "whatever your
MCP client is comfortable with."
Related MCP server: kcc-epub-converter
Setup
Requires Python 3.10+, ffmpeg/ffprobe on PATH.
exiftool is also needed, but only for audiobook_embed_cover_metadata --
every other tool works without it (missing exiftool is reported clearly
by that one tool, not a silent skip). Likewise,
whisper.cpp is recommended
but not required: build/install it, put its CLI binary (whisper-cli or
whisper-cpp) on PATH (or point AUDIOBOOK_MCP_WHISPER_BIN at it
directly), download a GGML model with its models/download-ggml-model.sh
script, and set AUDIOBOOK_MCP_WHISPER_MODEL to that model file's path.
It's used by audiobook_transcribe_chapter_boundary (an on-demand spot
check) and, by default, by audiobook_start_conversion's
verify_first_chapter step (an automatic check of chapter 1's boundary
before the rest of the book is aligned). Without it, verify_first_chapter
falls back to a silence-only guess and logs a warning instead of failing
the job -- so whisper.cpp is worth setting up for any book that might have
an intro, but nothing breaks without it. No Python speech-recognition
package is installed by this project -- like ffmpeg and exiftool,
whisper.cpp is shelled out to as an external binary, and a missing
binary/model is reported clearly rather than silently skipped.
cd audiobook_mcp
pip install -e .
# or: pip install -r requirements.txtThis server targets v2.x of the MCP Python SDK (mcp>=2.0,<3.0.0).
v2 renamed FastMCP to MCPServer (now imported from
mcp.server.mcpserver, along with Context/Image) and changed the
@mcp.tool() decorator's annotations parameter from a plain dict to a
mcp.types.ToolAnnotations object, with title moving out to become the
decorator's own title= kwarg. Context.report_progress()/.info() and
the Image class kept the same call shape.
Register with an MCP client
Claude Code / Claude Desktop (claude_desktop_config.json or equivalent):
{
"mcpServers": {
"audiobook": {
"command": "python3",
"args": ["-m", "audiobook_mcp.server"],
"cwd": "/absolute/path/to/audiobook_mcp"
}
}
}Or, after pip install -e ., use the installed console script instead of
-m audiobook_mcp.server:
{
"mcpServers": {
"audiobook": { "command": "audiobook-mcp" }
}
}Tools
Tool | Purpose |
| Preview an EPUB's chapters/metadata/cover without starting a job. |
| Create (or resume) a job; runs the fast EPUB-parse stage only. |
| Advance a job by one bounded chunk of work. |
| Loop |
| Read a job's progress without doing work. |
| List known jobs (paginated). |
| List silence gaps found around a chapter's recorded boundary. |
| Render a waveform PNG around a boundary, for a visual spot-check. |
| Transcribe the audio at a boundary via whisper.cpp, for a text-based spot-check. |
| Manually fix a flagged/fallback chapter boundary. |
| Sanity-check a finished M4B (chapters, duration, cover art). |
| Remove a job (optionally deleting its scratch files). |
| Look up book/audiobook metadata + cover candidates across free APIs. |
| Download a chosen cover URL to disk. |
| Write a metadata record into a cover image's EXIF/XMP/IPTC tags. |
Typical flow: start_conversion → loop run_until_done (or
continue_conversion) until done. The first thing that loop does, before
aligning any other chapter, is confirm chapter 1's own boundary by
transcript (verify_first_chapter, on by default -- see get_status's
alignment.chapter_1_anchor for its outcome); everything from chapter 2
onward chains forward from whatever chapter 1's boundary turns out to be,
so getting it right up front avoids having to patch every later chapter
individually if it were wrong. Once done, if get_status still shows
fallback_chapters or word_count_warnings for some other chapter, use
inspect_chapter_boundary (+ optionally render_boundary_waveform for a
visual check, or transcribe_chapter_boundary for a text check against
the EPUB's own chapter opening) to find the right cut, then
patch_chapter_boundary and resume → finally verify_output on the
result.
flowchart TD
A["start_conversion"] --> V["verify_first_chapter:\ntranscribe candidates near\nfile start vs. EPUB ch.1 text"]
V --> B["loop: run_until_done\n(or continue_conversion) --\nchapters 2..N chain forward\nfrom chapter 1's boundary"]
B --> C{"done?"}
C -- "no" --> B
C -- "yes" --> D{"get_status shows\nfallback_chapters or\nword_count_warnings?"}
D -- "no" --> G["verify_output"]
D -- "yes" --> E["inspect_chapter_boundary"]
E --> F1["render_boundary_waveform\n(visual check)"]
E --> F2["transcribe_chapter_boundary\n(text check vs. EPUB)"]
F1 --> P["patch_chapter_boundary"]
F2 --> P
P -- "resume" --> BThe last three tools are a mostly-independent workflow (ported from
the book-metadata-fetch skill, see third_party/book-metadata-fetch/
for the original and evaluations/README.md-adjacent test coverage in
tests/test_metadata_fetch.py): lookup_book_metadata (by title/author,
no local files needed) → review its _conflicts before trusting a field
→ fetch_cover_image on whichever candidate has the best measured
pixel dimensions → embed_cover_metadata on the downloaded file. Same
guardrails as the source skill: personal research/cataloging use, no
Amazon/Audible page scraping (that needs a browser tool this server
doesn't have -- Tier 1 here is the ceiling), never loop it over long
title lists. The one bridge between the two workflows: pass
fetch_cover_image's downloaded path as start_conversion's
cover_image_path to use a fetched cover instead of whatever (if
anything) is in the source EPUB.
Jobs, state, and where things live
Each job's state of record is
<out_dir>/.state/<job_id>/state.json— self-contained (it stores its own config), so it's the source of truth even if the registry below is lost.A lightweight registry mapping
job_id -> work_dirpersists at$AUDIOBOOK_MCP_HOME/registry.json(default~/.audiobook_mcp/), so jobs survive a server restart without the caller re-supplying paths.Once a job reaches
"done", its encoded segments and assembly scratch data are deleted automatically; the checkpoint and logs remain.
Security notes
This server operates with the filesystem permissions of the process
running it, by design — like a CLI tool, not a multi-tenant web service.
mp3_path/epub_path/out_dir/m4b_path are used as given (validated
for existence/type, not sandboxed to a subtree). Only run this server in
contexts where you trust whoever can call its tools with your local
filesystem access. All ffmpeg/ffprobe invocations use argument lists
(never shell=True), so filenames with spaces or shell metacharacters
can't cause command injection.
Testing
uv sync --group dev
uv run pytest -vtests/conftest.py's session-scoped fixture_dir fixture calls
evaluations/make_fixture.py to synthesize a tiny 4-chapter "book" (EPUB +
a ~40s MP3 built from distinct tones and real silence gaps, including one
deliberately-placed decoy gap) so the full pipeline — alignment, decoy
filtering, encoding, muxing, cover embedding, delivery — can be exercised
in seconds without a real audiobook. test_smoke.py runs the actual
Pipeline class (the same code every tool in server.py calls) against
it end-to-end and asserts on the result, including an independent
re-scan of the audio to confirm the real gap (not the decoy) was chosen.
audiobook_lookup_book_metadata's four source APIs
(googleapis.com/openlibrary.org/api.audible.com/itunes.apple.com) aren't
reachable from every environment (they weren't from the one this server
was built in — see that test file's module docstring). Its ported
reconciliation/ranking logic is instead tested against fixture payloads
built from the source skill's own documented failure modes (series
volume mismatches, far-future re-issues, publisher/date conflicts) in
tests/test_metadata_fetch.py, which also runs a real exiftool
embed+readback. tests/test_tool_integration.py drives the actual MCP
tool functions (Pydantic validation included) via a file:// URL so the
download code path is real too. Before relying on lookup_book_metadata
in production, also run a handful of lookups somewhere with network
access to those four APIs.
See evaluations/README.md for the Phase 4 agent-facing evaluation set
and why it's built the way it is.
What's deliberately out of scope (v1)
No-EPUB fallback. The skill documents a manual workaround for books with no EPUB at all (hand-authored chapter durations instead of word-count-based sanity checking). Not implemented as a tool here — EPUB is a required input, as in the skill's own
run.py.Concurrent processing of the same job from two callers is guarded by an in-process lock per
job_id, but the server assumes a single server process (not multiple replicas sharing oneout_dir).Tier 2 Amazon/Audible retail-page fallback from the
book-metadata-fetchskill (seethird_party/book-metadata-fetch/) isn't reimplemented: it depends on a browser automation tool this server doesn't have.audiobook_lookup_book_metadatacovers Tier 1 (Google Books, Open Library, Audible's public catalog search, Apple iTunes) only; a calling agent with its own browser tool may attempt the source skill's Tier 2 procedure manually, subject to the same guardrails (never bypass a CAPTCHA/sign-in wall, one on-demand lookup per title).
Available Tools
15 toolsaudiobook_cancel_conversionRemove a conversion jobADestructiveIdempotent
Remove a job from the registry. By default this only forgets the job_id (the on-disk state under out_dir/.state/<job_id> is left alone, so audiobook_start_conversion with the same mp3/epub/out_dir would still resume it). With delete_files=True, also deletes that scratch directory -- the original mp3/epub and anything already delivered into out_dir itself are never touched either way.
Args: params (CancelConversionInput): - job_id (str). - delete_files (bool): also delete the job's working directory.
Returns: str: JSON {"job_id": str, "removed_from_registry": true, "files_deleted": bool} or {"error": ...} if job_id is unknown.
Inputs: params (required). Returns: result
audiobook_continue_conversionAdvance a conversion job by one bounded chunk of workA
Do up to time_budget_seconds of work on a job (aligning chapters, encoding segments, assembling, or delivering the final file -- whichever stage it's currently in), checkpoint to disk, and return. Re-call this with the same job_id, or use audiobook_run_until_done to loop automatically, until the response's "done" field is true.
Safe to call again immediately if a previous call errored partway through a stage -- work already checkpointed is never redone.
Args: params (ContinueConversionInput): - job_id (str): from audiobook_start_conversion. - time_budget_seconds (float): stop and checkpoint after roughly this long (5-300s, default 60).
Returns: str: JSON status object -- see audiobook_get_status's Returns schema, which this shares exactly.
Error Handling: - "unknown_job" if job_id isn't registered. - ffmpeg/encoding failures surface with ffmpeg's own error text tail included; the job's checkpoint is untouched so retrying (after e.g. freeing disk space) picks up where it left off.
Inputs: params (required). Returns: result
audiobook_embed_cover_metadataEmbed a metadata record into a cover image's EXIF/XMP/IPTC tagsADestructiveIdempotent
Write a book metadata record into an existing image file's EXIF/XMP/IPTC tags via exiftool (title, creator/artist, description, publisher, copyright, date, keywords, source URL, rating). Narrator and length have no standard EXIF equivalent, so the complete record is also stamped into the JPEG Comment field as JSON so nothing is lost. Overwrites image_path's own metadata in place -- the image's pixel data is untouched.
Requires exiftool on PATH; if it's missing this tool errors rather than silently skipping the embed (per the source skill's guardrail).
Args: params (EmbedCoverMetadataInput): - image_path (str): the image file to tag (typically the output of audiobook_fetch_cover_image). - metadata (BookMetadataInput): the record to embed, e.g. straight from audiobook_lookup_book_metadata's "record". - dry_run (bool): if true, return the exiftool command without writing anything.
Returns: str: JSON {"command": [str, ...], "output": str|null, "dry_run": bool} or {"error": ...} if image_path doesn't exist or exiftool fails/is missing.
Inputs: params (required). Returns: result
audiobook_fetch_cover_imageDownload a cover image URL to diskA
Download a specific cover image URL (typically one from
audiobook_lookup_book_metadata's covers array -- pick by measured
width/height, not source order or URL) to out_dir, and report its
real decoded pixel dimensions. Saved as
"_.jpg" (or without the author
suffix if none given), matching the source skill's naming convention.
Args: params (FetchCoverImageInput): - cover_url (str): the image URL to download. - out_dir (str): destination directory (created if missing). - title/author (str): used to build the filename. - overwrite (bool): default False errors instead of clobbering an existing file with the same name.
Returns: str: JSON {"path": str, "width": int|null, "height": int|null, "bytes": int} or {"error": ...} on failure.
Error Handling: - Errors (not overwrites) if a file with the computed name already exists and overwrite=False. - Network failures surface with the underlying reason.
Inputs: params (required). Returns: result
audiobook_get_statusRead a conversion job's current statusARead-onlyIdempotent
Read a job's current progress WITHOUT doing any work -- safe to call as often as you like, including while another audiobook_continue_conversion/audiobook_run_until_done call might be in flight.
Args: params (JobIdInput): - job_id (str): from audiobook_start_conversion.
Returns: str: JSON with schema: { "stage": str, # "extract"|"align"|"encode"|"assemble"|"deliver"|"done" "done": bool, "status_line": str, # most recent human-readable progress line "overall_progress": float, # 0.0-1.0 across the WHOLE job, comparable # across separate continue_conversion/ # run_until_done calls -- suitable for a # progress bar. Weighted by each stage's # typical share of total time (encode # dominates), not just "stages done / 6". "overall_progress_pct": float, # overall_progress * 100, rounded to 1 decimal "book": {"title", "author", "series", "series_index", "chapter_count", "cover_found"} | null, "alignment": { # present once alignment has started "chapters_aligned": int, "chapters_total": int, "low_confidence_chapters": [int, ...], # spot-check these "fallback_chapters": [int, ...], # these need a fix "manual_overrides": [int, ...], "outro_detected": bool } | absent, "encoding": {"segments_encoded": int, "segments_total": int} | absent, "word_count_warnings": [ {"n": int, "title": str, "actual_duration_s": float, "expected_duration_s": float} ] | absent, # segments whose duration deviates >30% from EPUB word-count pace "assembled_path": str | absent, "delivery": {"bytes_done": int, "bytes_total": int} | absent, "final_output": str | absent, # present once stage == "done" "recent_log": [str, ...] # last 10 status lines } or {"error": str, "error_type": str} if job_id is unknown.
Examples: - Use when: checking whether a long-running job has finished yet. - Use when: deciding whether fallback_chapters/word_count_warnings need audiobook_inspect_chapter_boundary + audiobook_patch_chapter_boundary before trusting the output.
Inputs: params (required). Returns: result
audiobook_inspect_chapter_boundaryList silence gaps found around a chapter's recorded boundaryARead-onlyIdempotent
Re-scan the audio around a chapter's currently recorded boundary and list every silence gap found, so you (or the user) can judge whether the recorded boundary is the right one -- most useful for a chapter that showed up in fallback_chapters or word_count_warnings from audiobook_get_status. Does not change anything; follow up with audiobook_render_boundary_waveform for a visual, or audiobook_patch_chapter_boundary once you've picked the right gap.
Args: params (InspectBoundaryInput): - job_id (str), chapter_index (int, 1-based). - window_seconds (float): half-width of the search region around the current boundary (default 30). - noise_db / min_silence (float): silencedetect thresholds -- widen noise_db (e.g. -25) for a loud passage, shorten min_silence to catch briefer pauses.
Returns: str: JSON with schema: { "chapter_index": int, "current_boundary_seconds": float, "search_window": {"start": float, "end": float}, "gaps_found": [ {"start": float, "end": float, "duration": float, "distance_from_current_boundary": float} ] # sorted by distance from the current boundary } or {"error": ...} if the chapter hasn't been aligned yet.
Error Handling: - Raises a clear error if chapter_index hasn't been reached by alignment yet (check audiobook_get_status's "alignment" field first).
Inputs: params (required). Returns: result
audiobook_inspect_epubPreview an EPUB's chapters and metadataARead-onlyIdempotent
Parse an EPUB and preview the book metadata, chapter list, and cover art the audiobook pipeline would use, WITHOUT touching any audio file or creating a conversion job. Use this before audiobook_start_conversion to sanity-check chapter detection (e.g. spot an EPUB with an unusual structure) or to answer questions like "how many chapters does this book have" without needing the MP3 yet.
Args: params (InspectEpubInput): - epub_path (str): Absolute path to the .epub file.
Returns: str: JSON with schema: { "title": str, "author": str, "series": str, "series_index": str, "year": str, "cover_found": bool, "chapter_count": int, "total_word_count": int, "first_chapters": [{"n": int, "title": str, "word_count": int}, ...], # up to 3 "last_chapters": [{"n": int, "title": str, "word_count": int}, ...] # up to 3 } or {"error": str, "error_type": str} on failure.
Error Handling: - "epub_extract_error" style errors if the file isn't a valid EPUB or no chapters could be located at all (e.g. no TOC and no spine items pass the front/back-matter filter).
Inputs: params (required). Returns: result
audiobook_list_conversionsList known conversion jobsARead-onlyIdempotent
List jobs known to this server (persisted at $AUDIOBOOK_MCP_HOME/registry.json, default ~/.audiobook_mcp/), most recently created first.
Args: params (ListConversionsInput): - out_dir (Optional[str]): if set, only jobs whose output directory matches exactly. - limit (int): max jobs to return (1-100, default 20). - offset (int): pagination offset (default 0).
Returns: str: JSON with schema: { "total": int, "count": int, "offset": int, "jobs": [ {"job_id": str, "mp3": str, "epub": str, "out_dir": str, "work_dir": str, "created_at": float} ], "has_more": bool, "next_offset": int | null }
Inputs: params (required). Returns: result
audiobook_lookup_book_metadataLook up book/audiobook metadata and cover art candidatesARead-onlyIdempotent
Look up book/audiobook metadata (authors, narrators, publisher, publish date, description, ratings, ISBN, length) and candidate cover images across free, unauthenticated APIs: Google Books, Open Library, Audible's public catalog search, and Apple's iTunes Search. No scraping, login, or CAPTCHA surface is touched -- these are the same plain JSON endpoints each service's own search box calls.
Ported from the book-metadata-fetch skill; carries over its guardrails: personal research/cataloging use, not a bulk data feed -- this tool self-throttles slightly between calls, but don't loop it over long lists of titles. It has NO Amazon/Audible-retail-page fallback (that requires a browser tool this server doesn't have) -- if Tier 1 here comes up short, that's the tool's real ceiling; a calling agent with its own browser tool may attempt one manual, on-demand page visit per the source skill's Tier 2 procedure, subject to the same guardrails (never bypass a CAPTCHA/sign-in wall).
Series volumes are the main failure mode: search APIs rank by
relevance, not series order, so an unfiltered query for "Defiance of
the Fall" can return book 12. Include the volume number in title
when known (e.g. "Defiance of the Fall 6").
Args: params (LookupBookMetadataInput): see field descriptions. Notably reconcile=True (default) merges all sources into one record; include_covers=True (default) probes each candidate cover's real pixel dimensions (never trust a CDN URL's size token).
Returns: str: JSON. With reconcile=True: { "record": { "title": str, "authors": [str,...], "narrators": [str,...], "description": str, "publisher": str, "published_date": str, "categories": [str,...], "average_rating": float, "ratings_count": int, "length": str, "isbn": str, "source_url": str, "_provenance": {field: source_name}, # which source supplied each field "_conflicts": [str, ...], # fields sources disagreed on -- READ THESE # before trusting publisher/published_date; # audiobook vs. print edition is the common case "_missing": [str, ...] # fields nothing supplied }, "errors": {source_name: error_message}, "covers": [ # present if include_covers=True {"source": str, "url": str, "width": int|null, "height": int|null, "bytes": int} | {"source": str, "url": str, "error": str} ] } With reconcile=False: {"raw": {source_name: [...]}, "errors": {...}, "covers": [...]}.
Error Handling: - Per-source failures land in "errors" rather than failing the whole call -- e.g. Google Books commonly 429s on its shared anonymous quota; the other three sources still return. - Only fails outright ({"error": ...}) if input validation fails.
Inputs: params (required). Returns: result
audiobook_patch_chapter_boundaryManually override a chapter's detected boundaryADestructive
Manually fix a chapter boundary that landed in the wrong place (surfaced via fallback_chapters, low_confidence_chapters, or word_count_warnings). This overwrites the recorded boundary for chapter_index and invalidates every stage derived from it -- encoded segments, the assembled file, and delivery all get regenerated on the next audiobook_continue_conversion/audiobook_run_until_done call. Chapters before and after chapter_index are untouched, so this is always cheaper than restarting the whole job.
Args: params (PatchBoundaryInput): - job_id (str), chapter_index (int, 1-based). - new_start_seconds (float): the corrected boundary, typically the midpoint of a gap surfaced by audiobook_inspect_chapter_boundary.
Returns: str: JSON with schema: { "chapter_index": int, "old_start_seconds": float, "new_start_seconds": float, "invalidated": [str, ...], # state keys cleared, e.g. "segments", "encode_progress" "stage_now": str # call audiobook_continue_conversion next } or {"error": ...} if chapter_index hasn't been aligned yet or new_start_seconds is out of range.
Inputs: params (required). Returns: result
audiobook_render_boundary_waveformRender a waveform image around a chapter boundaryAIdempotent
Render a PNG waveform snapshot centered on a chapter's current recorded boundary (or on center_override_seconds, e.g. a candidate gap surfaced by audiobook_inspect_chapter_boundary). A clean cut shows an obvious gap centered in the image with speech clusters on both sides; if the gap looks off-center or absent, the boundary likely needs audiobook_patch_chapter_boundary.
Args: params (RenderWaveformInput): - job_id (str), chapter_index (int, 1-based). - half_window_seconds (float): half-width of the rendered window (default 8). - center_override_seconds (Optional[float]): render around this timestamp instead of the recorded boundary.
Returns: Image: a PNG waveform image.
Error Handling: - Raises a clear error if chapter_index hasn't been aligned yet and no center_override_seconds was given.
Inputs: params (required).
audiobook_run_until_doneLoop a conversion job forward until it finishes or a time cap is hitA
Repeatedly advance a job in chunk_seconds increments, reporting progress, until either it finishes or max_total_seconds elapses -- whichever comes first. This is the convenient one-call way to drive a job; use audiobook_continue_conversion directly instead if you want fine-grained control over each chunk (e.g. to react to a warning partway through).
For a long book this may still return with "done": false if max_total_seconds wasn't enough -- just call it again with the same job_id to keep going; already-completed work is never redone.
Args: params (RunUntilDoneInput): - job_id (str): from audiobook_start_conversion. - chunk_seconds (float): size of each internal step (default 60). - max_total_seconds (float): overall cap for this call (default 1200s / 20 min).
Returns: str: JSON status object (same schema as audiobook_get_status) plus: - "elapsed_seconds" (float): how long this call actually ran. - "chunks_run" (int): how many internal chunks it took.
Error Handling: - Same as audiobook_continue_conversion. If a chunk raises partway through the loop, the loop stops immediately and the error is returned -- prior chunks in this call are already checkpointed.
Inputs: params (required). Returns: result
audiobook_start_conversionStart (or resume) an audiobook -> M4B conversion jobAIdempotent
Create a resumable conversion job for one MP3/M4A audiobook + its EPUB, and run the fast first stage (EPUB parsing + audio duration probe). This does NOT do the slow chapter-alignment/encoding work -- call audiobook_continue_conversion or audiobook_run_until_done next, and loop until the response's "done" field is true.
Calling this again with the exact same mp3_path/epub_path/out_dir resumes the existing job (returning its current status) instead of creating a duplicate, unless force_restart=True.
Args: params (StartConversionInput): see field descriptions. Notably: - mp3_path/epub_path (str): source files, must both exist. - out_dir (str): where the finished .m4b will be written. - cover_image_path (Optional[str]): use this image instead of the EPUB's own cover. Typical flow: audiobook_lookup_book_metadata -> audiobook_fetch_cover_image -> pass the downloaded path here. - verify_first_chapter (bool): on by default. Confirms chapter 1's actual start via whisper.cpp transcription before any other chapter is aligned, since every later chapter is chained forward from it -- an unconfirmed guess there (typically a missed intro) otherwise throws off the whole book. Falls back to the old silence-only heuristic and logs a warning if whisper.cpp isn't configured; never fails the job. - detect_intro/detect_outro (bool): off by default; only turn on if the user has confirmed the book has an audible intro/outro segment (see tool description in code for why). detect_intro only takes effect as verify_first_chapter's fallback -- see its own field description.
Returns: str: JSON with schema: { "job_id": str, # pass this to every other job tool "stage": str, # "align" once extract succeeds "book": {"title", "author", "series", "series_index", "chapter_count", "cover_found"}, "next_step": str # what to call next } or {"error": str, "error_type": str} on failure.
Error Handling: - "ffmpeg_missing" if ffmpeg/ffprobe aren't on PATH. - Otherwise a PipelineError/EpubExtractError with a specific reason (file not found, wrong extension, unparseable EPUB, ...).
Inputs: params (required). Returns: result
audiobook_transcribe_chapter_boundaryTranscribe the audio right after a chapter boundaryAIdempotent
Transcribe a few seconds of audio starting at a chapter's current recorded boundary (or center_override_seconds, e.g. a candidate gap surfaced by audiobook_inspect_chapter_boundary) via a local whisper.cpp install -- a text-based alternative/complement to audiobook_render_boundary_waveform for judging a low_confidence or fallback boundary. Compare the transcript against expected_opening_text (pulled straight from the EPUB's own chapter text): a rough match means the cut is clean; a transcript that trails off from the PREVIOUS chapter's content means the boundary landed too late; one missing this chapter's first words means it landed too early.
Requires whisper.cpp (https://github.com/ggerganov/whisper.cpp) on
PATH as whisper-cli or whisper-cpp (or AUDIOBOOK_MCP_WHISPER_BIN
pointing at its CLI binary directly), plus a downloaded GGML model
file referenced by AUDIOBOOK_MCP_WHISPER_MODEL -- no Python
speech-recognition dependency. Missing either is reported clearly,
not silently skipped.
Args: params (TranscribeBoundaryInput): - job_id (str), chapter_index (int, 1-based). - duration_seconds (float): how much audio to transcribe, starting at the boundary (default 12). - language (str): whisper.cpp language code (default "en") -- set to the book's actual spoken language. - center_override_seconds (Optional[float]): transcribe starting here instead of the recorded boundary.
Returns: str: JSON with schema: { "chapter_index": int, "start_seconds": float, "duration_seconds": float, "transcript": str, # "" if the clip is silent/inaudible "expected_opening_text": str | absent # first ~40 words of this chapter's # own EPUB text, if available } or {"error": str, "error_type": str} on failure.
Error Handling: - "dependency_missing" if ffmpeg or whisper.cpp (binary or model) aren't available -- see the tool description for setup. - Raises a clear error if chapter_index hasn't been aligned yet and no center_override_seconds was given.
Inputs: params (required). Returns: result
audiobook_verify_outputSanity-check a finished M4BARead-onlyIdempotent
Run the same checks the skill recommends before handing a result back: chapter count, total duration (optionally cross-checked against the original source file), first/last chapter titles, and whether a cover-art video stream is present.
Args: params (VerifyOutputInput): - m4b_path (str): the file to verify. - source_audio_path (Optional[str]): original mp3/m4a, for a duration cross-check. - expected_chapter_count (Optional[int]): compare against this.
Returns: str: JSON with schema: { "duration_seconds": float, "chapter_count": int, "first_chapter_title": str, "last_chapter_title": str, "has_cover_art": bool, "source_duration_seconds": float | absent, "duration_difference_seconds": float | absent, "issues": [str, ...] # empty list means everything checked out } or {"error": ...} if m4b_path can't be probed by ffprobe.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct operation: job lifecycle, status, boundary inspection/correction, output verification, and metadata handling are all clearly separated. Even similar tools like continue_conversion and run_until_done are explicitly differentiated by chunked vs. looping behavior.
All tools use the consistent audiobook_ prefix followed by verb_noun snake_case names (start_conversion, get_status, patch_chapter_boundary). This makes the intended action and target resource predictable across the entire toolset.
At 15 tools, the server is at the upper end of a well-scoped set, but every tool serves a distinct and necessary purpose in the audiobook pipeline. The count feels appropriate for covering conversion, progress tracking, boundary QA, verification, and metadata enrichment without redundant clutter.
The toolset provides a complete workflow: inspect EPUB, start/resume/run/cancel jobs, monitor progress, verify output, handle boundary corrections, and fetch/embed cover metadata. There are no obvious dead ends or missing lifecycle operations for the stated audiobook conversion purpose.
Related MCP Connectors
EPUB/PDF tools: merge, split, compress, convert, edit metadata, validate ebooks.
Turn matching Mandarin or Japanese and English audio into one interleaved listening MP3.
Turn PDFs, Word, EPUB and X posts into narrated audio with word-level timestamps.
Convert scanned PDFs to Markdown or EPUB, and translate PDF and EPUB books via MCP.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceHosted Streamable HTTP MCP server (https://epublys.com/mcp) with 12 tools for EPUB/PDF manipulation: merge, split, compress, EPUB<->PDF, EPUB<->Markdown and DOCX->EPUB conversion, metadata read/edit, validation with auto-fix, and AI cover generation (Pro). Nothing to install and no API key needed for the free tier; a free key from https://epublys.com/account carries your account allowance and Pro.-
- FlicenseNot gradedqualityDmaintenanceConverts large comic archives (CBZ/CBR) into Kindle-optimized EPUB volumes with GPU acceleration, smart chunking under Amazon's 200MB limit, and device-specific profiles for manga/comics.-
- AlicenseNot gradedqualityDmaintenanceTurns PDF or EPUB books into reusable AI analysis, Obsidian notes, and agent Skills that can be installed into Codex, Claude Code, or other MCP clients.56MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP server that turns any text into narration, voice-overs, dialogues, audiobook chapters and per-shot video clips as MP3/WAV files — with emotions, acting modes, inline cues, presets and subtitles — driven by a ChatGPT sign-in rather than an API key. It also exposes tools for inspecting audio (timings, pace, pitch, waveform), transcribing recordings, listing and favouring voices, saving pronunciation presets, and checking sign-in status.MIT