Skip to main content
Glama

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.txt

This 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

audiobook_inspect_epub

Preview an EPUB's chapters/metadata/cover without starting a job.

audiobook_start_conversion

Create (or resume) a job; runs the fast EPUB-parse stage only.

audiobook_continue_conversion

Advance a job by one bounded chunk of work.

audiobook_run_until_done

Loop continue_conversion internally up to a time cap.

audiobook_get_status

Read a job's progress without doing work.

audiobook_list_conversions

List known jobs (paginated).

audiobook_inspect_chapter_boundary

List silence gaps found around a chapter's recorded boundary.

audiobook_render_boundary_waveform

Render a waveform PNG around a boundary, for a visual spot-check.

audiobook_transcribe_chapter_boundary

Transcribe the audio at a boundary via whisper.cpp, for a text-based spot-check.

audiobook_patch_chapter_boundary

Manually fix a flagged/fallback chapter boundary.

audiobook_verify_output

Sanity-check a finished M4B (chapters, duration, cover art).

audiobook_cancel_conversion

Remove a job (optionally deleting its scratch files).

audiobook_lookup_book_metadata

Look up book/audiobook metadata + cover candidates across free APIs.

audiobook_fetch_cover_image

Download a chosen cover URL to disk.

audiobook_embed_cover_metadata

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" --> B

The 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_dir persists 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 -v

tests/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 one out_dir).

  • Tier 2 Amazon/Audible retail-page fallback from the book-metadata-fetch skill (see third_party/book-metadata-fetch/) isn't reimplemented: it depends on a browser automation tool this server doesn't have. audiobook_lookup_book_metadata covers 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 tools
audiobook_cancel_conversionRemove a conversion jobA
DestructiveIdempotent

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 tagsA
DestructiveIdempotent

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 statusA
Read-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 boundaryA
Read-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 metadataA
Read-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 jobsA
Read-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 candidatesA
Read-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 boundaryA
Destructive

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 boundaryA
Idempotent

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 jobA
Idempotent

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 boundaryA
Idempotent

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 M4BA
Read-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

    A4.6/5.0

    Scored across 15 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Hosted 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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