Metadata-Version: 2.5
Name: claudio-audiobook
Version: 0.1.4
Summary: Turn text or a whole generated course into an audiobook with local Kokoro voices. MCP server for Claude Code and Claude Desktop.
Project-URL: Homepage, https://github.com/restante/claudio_audiobook
Project-URL: Repository, https://github.com/restante/claudio_audiobook
Project-URL: Issues, https://github.com/restante/claudio_audiobook/issues
Project-URL: Changelog, https://github.com/restante/claudio_audiobook/blob/main/CHANGELOG.md
Author: Claudio Restante
License-Expression: MIT
License-File: LICENSE
Keywords: audiobook,claude-code,claude-desktop,kokoro,mcp,text-to-speech,tts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: imageio-ffmpeg>=0.5.1
Requires-Dist: kokoro-onnx>=0.5.0
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: mistune>=3.0.0
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.1
Requires-Dist: psutil>=5.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.restante/claudio-audiobook -->
<div align="center">

# 🎧 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

[![CI](https://github.com/restante/claudio_audiobook/actions/workflows/ci.yml/badge.svg)](https://github.com/restante/claudio_audiobook/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/restante/claudio_audiobook/blob/main/LICENSE)
[![Release](https://img.shields.io/github/v/release/restante/claudio_audiobook)](https://github.com/restante/claudio_audiobook/releases)
[![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![Runs locally](https://img.shields.io/badge/runs-100%25%20locally-brightgreen)

[**Install**](#install-in-60-seconds) · [**Listen**](#hear-it) · [**Examples**](#examples) · [**Voices**](#54-voices-9-languages) · [**Settings**](#every-setting)

<!-- HERO: docs/img/hero.gif — see docs/SCREENSHOTS.md, shot 1. Add it here once captured. -->

</div>

---

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

| Tool | How to install |
|---|---|
| Claude Desktop | one-click `.mcpb` extension |
| Claude Code | plugin, or `claude mcp add` |
| Cursor | [`mcp.json`](#other-ai-tools) |
| VS Code (GitHub Copilot) | [`mcp.json`](#other-ai-tools) |
| Gemini CLI | [`settings.json`](#other-ai-tools) |
| Codex CLI (OpenAI) | [`config.toml`](#other-ai-tools) |
| Any other MCP client, or no AI | stdio command / [command line](#command-line) |

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](https://huggingface.co/hexgrad/Kokoro-82M) 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`](https://github.com/restante/claudio_audiobook/blob/main/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](https://docs.astral.sh/uv/) for Claude Code ([install it](https://docs.astral.sh/uv/getting-started/installation/):
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

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

Prefer just the MCP server, without the skill?

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

### Claude Desktop

1. Download `claudio-audiobook-<version>.mcpb` from [Releases](https://github.com/restante/claudio_audiobook/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:

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

<details>
<summary><b>Cursor</b> · <code>~/.cursor/mcp.json</code> or <code>.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "claudio-audiobook": {
      "type": "stdio",
      "command": "claudio-audiobook-mcp"
    }
  }
}
```
</details>

<details>
<summary><b>VS Code (GitHub Copilot)</b> · <code>.vscode/mcp.json</code> or run <i>MCP: Open User Configuration</i></summary>

```json
{
  "servers": {
    "claudio-audiobook": {
      "type": "stdio",
      "command": "claudio-audiobook-mcp"
    }
  }
}
```
Use agent mode so Copilot can call tools.
</details>

<details>
<summary><b>Gemini CLI</b> · <code>~/.gemini/settings.json</code></summary>

```json
{
  "mcpServers": {
    "claudio-audiobook": {
      "command": "claudio-audiobook-mcp"
    }
  }
}
```
or `gemini mcp add --scope user claudio-audiobook claudio-audiobook-mcp`. Check with `/mcp`.
</details>

<details>
<summary><b>Codex CLI (OpenAI)</b> · <code>~/.codex/config.toml</code></summary>

```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`.
</details>

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](#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](https://github.com/restante/claudio_audiobook/issues).

## 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**

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

<!-- SCREENSHOT: Claude Desktop chat producing a course — docs/img/desktop-chat.png (docs/SCREENSHOTS.md, shot 2) -->
![Cover, tags and chapter list read from a finished .m4b](https://raw.githubusercontent.com/restante/claudio_audiobook/main/docs/img/chapters-card.png)

<!-- SCREENSHOT: the finished .m4b in Apple Books / Podcasts showing chapters — docs/img/chapters.png (shot 3) -->

### Command line

A real run (from [`docs/samples/python-intro.md`](https://github.com/restante/claudio_audiobook/blob/main/docs/samples/python-intro.md)): three chapters in, one `.m4b`
with chapter marks out.

![Terminal: claudio-audiobook builds an m4b with three chapters](https://raw.githubusercontent.com/restante/claudio_audiobook/main/docs/img/terminal.png)


No Claude needed for text you already have:

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

Preview before rendering. This is real output:

```text
$ 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.

<img src="https://raw.githubusercontent.com/restante/claudio_audiobook/main/docs/img/cover-example.jpg" alt="A generated title cover" width="220" align="right">

- **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:

| Where | How |
|---|---|
| **Apple Books** (Mac, iPhone, iPad) | drag the `.m4b` onto Books, or share it from Files |
| **BookPlayer** (iOS, chapters tested), **Audiobookshelf**, **Plex** | add it to the library folder or import it |
| **Voice**, **Smart AudioBook Player**, **Listen** (Android) | open the file or copy it to your audiobooks folder |
| VLC, Foobar2000 | plays it. VLC for iOS did not show the chapter list in testing, so use BookPlayer or Apple Books for chapters |

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

```text
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.

| Setting | CLI flag | Values | Default |
|---|---|---|---|
| voice | `--voice` | a name (`af_heart`, `bf_emma`, `im_nicola`, … 54 voices, 9 languages) or a blend `af_heart:0.6,af_sky:0.4` | `af_heart` |
| speed | `--speed` | 0.5 to 2.0 | 1.0 |
| language | `--lang` | espeak code, e.g. `de`; lets a voice read another language with an accent | the voice's own |
| model | `--model` | `full` (best) or `lite` (92 MB, faster) | `full` |
| format | `--format` | `m4b` (chapters), `mp3`, `wav` | `m4b` |
| sentence pause | `--sentence-pause` | 0 to 5 seconds | 0.25 |
| clause pause | `--clause-pause` | 0 to 5 seconds (after commas, colons) | 0.1 |
| chapter pause | `--chapter-pause` | 0 to 30 seconds | 1.5 |
| trim | `--no-trim` | cut silence at sentence ends, or keep it | trim |
| author | `--author` | shown by players as the author | `CLAUDIO_AUDIOBOOK_AUTHOR`, else none |
| narrator | `--narrator` | shown as the narrator | `Kokoro (<voice>)` |
| cover | `--cover` | `.jpg`/`.png` path, `none`, or leave out to generate a title cover | generated |
| cover colours | `--cover-colors` | `#top,#bottom` for the generated cover | picked from the title |
| output folder | `-o` / `output_dir` | any folder | `~/Audiobooks/<title>` |

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

## How it works

```text
 "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](#hear-it). 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`](https://github.com/restante/claudio_audiobook/blob/main/CLAUDE.md) for architecture and rules.

```bash
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](https://huggingface.co/hexgrad/Kokoro-82M) via
[kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx).
