claudio-audiobook

🎧 claudio-audiobook

An MCP server that lets your AI assistant make audiobooks

Say "create a python course audiobook". The AI writes it, a local voice reads it. Free, private, offline.

Works with Claude Desktop · Claude Code · Cursor · VS Code (Copilot) · Gemini CLI · Codex CLI · any MCP client

**Install** · **Listen** · **Examples** · **Voices** · **Settings**

What it is

claudio-audiobook is a Model Context Protocol (MCP) server. You add it to an AI assistant, and the assistant gains the ability to turn text into an audiobook on your computer. It is built and tested first for Claude (Desktop and Code, as a one-click extension and a plugin), and it works with other MCP-capable tools too. It also has a plain command line for use without any AI.

Not supported: web chat apps that cannot run local MCP servers (the ChatGPT and Gemini websites).

Why

Text-to-speech APIs charge per character and send your text to someone else's server. Audiobook apps only play books that already exist. claudio-audiobook closes the gap: you describe the audiobook you want, Claude writes it as spoken prose, and an 82M-parameter Kokoro voice reads it on your own machine.

| | claudio-audiobook | Cloud TTS APIs | Audiobook apps | |---|:-:|:-:|:-:| | Creates the content for you | ✅ | ❌ | ❌ | | Cost per hour of audio | £0 | per-character fees | subscription | | Text leaves your computer | Never | Always | n/a | | API key or account | None | Required | Required | | Chapters in the file (.m4b) | ✅ | DIY | ✅ | | Works offline after setup | ✅ | ❌ | partly |

Hear it

Real output, no editing. Voice bf_emma, from the text in docs/samples/python-intro.md:

▶ python-intro-bf_emma.mp3 (18 seconds, 109 KB)

That sample rendered in about 6 seconds on the author's Mac (CPU only). A real 11-chapter, 36-minute exam course took about 3 minutes.

Install in 60 seconds

You need uv for Claude Code (install it: macOS brew install uv, Windows winget install --id=astral-sh.uv -e). Everything else, including ffmpeg, is installed for you. The voice model (about 330 MB, once) downloads on first use.

Claude Code

/plugin marketplace add restante/claudio_audiobook
/plugin install claudio-audiobook --marketplace restante/claudio_audiobook

Prefer just the MCP server, without the skill?

claude mcp add claudio-audiobook -- uvx --from claudio-audiobook claudio-audiobook-mcp

Claude Desktop

1. Download claudio-audiobook-<version>.mcpb from Releases.
2. Open it with Claude Desktop (Settings → Extensions).
3. Optional: set your default voice, speed and folder in the extension's settings.

Desktop installs the dependencies itself.

Want the Pocket TTS engine in Desktop? Install claudio-audiobook-pocket-<version>.mcpb from the same Releases page instead of the standard one (install one or the other). It adds Pocket TTS (7 languages, voice cloning) and a "Default engine" setting. Its first launch downloads PyTorch and the voice engine, about 1 GB: under a minute on a fast connection in testing, longer on a slow one, and Claude may show the extension as failed until it finishes (wait, then reconnect).

Other AI tools

It is a standard MCP server (stdio), so it is not tied to Claude. Install it once, then point your tool at it:

uv tool install claudio-audiobook                                   # from PyPI; puts claudio-audiobook-mcp on your PATH
claudio-audiobook download-model                                    # the voice model, about 330 MB, once
claudio-audiobook doctor                                            # checks everything is in place

Installing first matters: the first run of uvx has to download and install everything, which can exceed a client's start-up timeout. If your tool cannot find the command, use its full path (which claudio-audiobook-mcp).

Cursor · ~/.cursor/mcp.json or .cursor/mcp.json

{
  "mcpServers": {
    "claudio-audiobook": {
      "type": "stdio",
      "command": "claudio-audiobook-mcp"
    }
  }
}

VS Code (GitHub Copilot) · .vscode/mcp.json or run MCP: Open User Configuration

{
  "servers": {
    "claudio-audiobook": {
      "type": "stdio",
      "command": "claudio-audiobook-mcp"
    }
  }
}

Use agent mode so Copilot can call tools.

Gemini CLI · ~/.gemini/settings.json

{
  "mcpServers": {
    "claudio-audiobook": {
      "command": "claudio-audiobook-mcp"
    }
  }
}

or gemini mcp add --scope user claudio-audiobook claudio-audiobook-mcp. Check with /mcp.

Codex CLI (OpenAI) · ~/.codex/config.toml

[mcp_servers.claudio-audiobook]
command = "claudio-audiobook-mcp"
startup_timeout_sec = 60

or codex mcp add claudio-audiobook -- claudio-audiobook-mcp. Codex waits only 10 seconds for a server to start by default, so raise startup_timeout_sec as above. Check with codex mcp list.

Set defaults (voice, speed, folder) with CLAUDIO_AUDIOBOOK_* environment variables in the same config, for example "env": { "CLAUDIO_AUDIOBOOK_VOICE": "bf_emma" }. Any agent that can run a shell can also use the command line directly.

Status: the server was checked with a generic MCP stdio client (handshake, tool list, a dry run), and the tool schemas are tested to avoid constructs that Cursor and Gemini mishandle. The configs above follow each tool's current documentation but have not yet been run inside those tools. If one doesn't work for you, please open an issue.

Examples

Just ask. Claude agrees the scope, writes the text, shows the chapter list and length, renders in the background and tells you where the file is.

A course from nothing

create a python course audiobook, for beginners, about an hour, in a calm British voice

Your own text

Turn ~/notes/book.md into an audiobook.

Steer it in plain English

slower · a different voice · mix af_heart and bf_emma 60/40 · longer pauses between sentences · make it mp3

Ideas people can do with it

• 🎓 Revision notes or an exam course you can listen to on the commute
• 📰 A long article or paper, read aloud while you cook
• 🧒 A bedtime story, in a voice you picked
• 🌍 Language practice: an Italian text read by if_sara, or an English text read with a French accent
• 💼 Onboarding docs or a team handbook as a podcast-style audio file

What you get

~/Audiobooks/python-for-beginners/
├── python-for-beginners.m4b      ← one file, with chapter marks
├── 01-welcome.wav
├── 02-variables.wav
└── ...

Command line

A real run (from docs/samples/python-intro.md): three chapters in, one .m4b with chapter marks out.

No Claude needed for text you already have:

uvx --from claudio-audiobook \
  claudio-audiobook build book.md --voice bf_emma --speed 0.95

Preview before rendering. This is real output:

$ claudio-audiobook build course.md --dry-run
  1  01-welcome.wav                                 ~  0.1 min
  2  02-variables.wav                               ~  0.1 min
  3  03-loops.wav                                   ~  0.1 min
3 chapters, about 0.0 h of audio

Chapters start at # headings (or lines like Chapter 3); a file without headings is cut into parts. Interrupted? Run it again: finished chapters are kept, and only chapters whose text or settings changed are redone.

Play it anywhere: chapters, tags and cover art

The default output is an M4B, the standard audiobook file: AAC audio with chapter marks, the tags players use to file it under Audiobooks (title, author, narrator, genre "Audiobook"), and a cover.

• Cover art is made for you, locally. Ask the AI for a look ("a dark green cover"): it picks the colours and passes them as cover_colors. Or give your own picture: "use ~/Pictures/cover.png" (--cover). A cover.jpg or cover.png you drop in the book's folder is used too. --cover none skips it.
• Author and narrator come from the chat ("by Ada Lovelace") or the --author flag. Set a default author once in the Desktop extension settings.
• The generated cover uses the built-in Latin font: titles in Chinese, Japanese or Korean show empty boxes, so give those books their own cover image.

Import it into:

Choose --format mp3 for players that don't read M4B (some car stereos). Audible and Kindle use closed formats and cannot import it.

Optional second engine: Pocket TTS

Pocket TTS (Kyutai, 100M parameters) is an optional second voice engine. In the author's small blind listening test (one listener) it was preferred for neutral English and its Italian was judged good. It is as fast as Kokoro on a laptop CPU (about 4x real time on an Apple M1), speaks English, Italian, French, German, Portuguese, Spanish and Dutch, has 27 built-in voices, and can clone a voice from a short clip. Kokoro stays the default.

uv tool install claudio-audiobook --with pocket-tts      # or: pip install claudio-audiobook pocket-tts
claudio-audiobook voices --engine pocket
claudio-audiobook build libro.md --engine pocket --lang it

Ask for it in chat: "use the pocket engine, in Italian". Differences from Kokoro, so nothing is silently ignored:

• No speed, clause_pause or trim settings (asking for another speed is an error). The sentence and chapter pauses work.
• voice is a catalogue name (alba, giovanni, ...) or the path of a clean 5 to 30 second clip to clone. Only clone a voice you have the right to use. Leave it out and each language gets its default voice (Italian: giovanni).
• In Claude Desktop, use the separate claudio-audiobook-pocket extension (see Install). The standard extension installs only the default dependencies and does not include Pocket TTS.
• Each language's model (about 400 MB) downloads once from Hugging Face the first time that language is used.
• Pocket TTS weights are © Kyutai, licensed CC BY 4.0; the code is MIT.

54 voices, 9 languages

American English: af_heart, af_bella, af_nova, am_adam, am_michael, ...
British English:  bf_emma, bf_isabella, bm_george, bm_lewis, ...
Italian:          if_sara, im_nicola
Spanish:          ef_dora, em_alex          French: ff_siwis
Hindi, Japanese, Brazilian Portuguese, Mandarin Chinese ...

Blend two voices into a new one: --voice af_heart:0.6,bf_emma:0.4. List them all with claudio-audiobook voices.

Every setting

Available as MCP tool arguments, CLI flags, and (for the first five, and the author) defaults in the Desktop settings or the CLAUDIO_AUDIOBOOK_* environment variables.

--dry-run shows the chapters and the estimated length without rendering. --force redoes everything. claudio-audiobook doctor checks the install.

How it works

 "create a python course"
          │
          ▼
   Claude writes spoken-style markdown   ← the skill / prompt teaches it to write for the ear
          │
          ▼
   MCP server: make_audiobook            ← runs as a detached job; survives a restart of Claude
          │
          ▼
   Kokoro (ONNX) renders each chapter    ← local, resumable, voice blends, pauses
          │
          ▼
   ffmpeg packs .m4b with chapter marks  ← bundled, nothing to install

Four MCP tools (make_audiobook, audiobook_status, list_voices, setup_check), a write_audiobook prompt and an audiobook skill. Works with any MCP client that can run a local stdio server.

Privacy

claudio-audiobook runs on your machine. Your text and audio are never uploaded, and there is no telemetry, no account and no API key.

It uses the network in two ways only: installing the package and its dependencies from PyPI (done by uv or pip), and a one-time download of the voice model: Kokoro from its GitHub release, checked against a SHA-256 sum, or, if you choose the optional Pocket engine, its model and voices from Hugging Face. It starts only its own programs: the bundled ffmpeg, a start-up check of the speech engine, and a background worker of this same package. It does not read or send credentials. Its settings are CLAUDIO_AUDIOBOOK_* environment variables, and only the home folder (~, $HOME) is ever expanded in a path.

FAQ

Does it cost anything? No. Claude itself is whatever plan you already have; the voice is free and local.

How good is the voice? Judge for yourself: listen to the sample. Kokoro is among the best small open TTS models, but it is not a human narrator. Expect clean, natural reading with occasional odd stress on unusual names.

Does it need a GPU? No. It runs on CPU.

Windows / Linux? The code is cross-platform and CI runs the tests. macOS is the tested path for Claude Desktop; Windows is not yet tested end to end. Reports welcome.

Can I use a different voice model? Point CLAUDIO_AUDIOBOOK_MODEL_FILE and CLAUDIO_AUDIOBOOK_VOICES_FILE at your own copy of the Kokoro files.

Contributing

Issues and PRs welcome, especially: Windows testing, new languages, and sample audiobooks. See CLAUDE.md for architecture and rules.

uv venv --python 3.12 && uv pip install -e ".[dev]" && .venv/bin/pytest

If this saved you a subscription, a ⭐ helps others find it.

MIT. Voices by Kokoro via kokoro-onnx.