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.

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.

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

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

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

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

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

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.

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 Kokoro voice model from its GitHub release, checked against a SHA-256 sum. 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.