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](https://modelcontextprotocol.io) (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](https://github.com/restante/claudio_audiobook/releases/download/v0.1.2/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- .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- .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" } } }

</details>

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 th