podcast-generator
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
podcast_generator
Converts markdown podcast scripts into spoken-word audio files, or into
narrated videos of PDF slides, using
voxport's KokoroDirectTTS for
local, offline-capable text-to-speech. No API key, no per-use cost, and
your scripts never leave your machine.
podcast-generator: converts scripts from the command line.Drop-folder mode: a Windows scheduled task converts whatever lands in an inputs folder (cloud-synced, if you like), controlled from the small Podcast Watch app (
podcast-watch).podcast-generator-mcp: an MCP server, so Claude Desktop or another MCP client can write, queue and convert podcasts and narrated briefings for you.
See it first: a six-minute introductory video (MP4, about 11 MB), made by podcast_generator itself from the example files.
This README is a quick start. See MANUAL.md for the full guide: script-writing conventions, complete CLI reference, the voice catalog, and troubleshooting.
Installation
Requires Python 3.10+. The command line works anywhere Kokoro does; the Podcast Watch app and scheduled drop-folder mode are Windows-only.
pip install podcast-generator # command line and Podcast Watch
pip install "podcast-generator[mcp]" # plus the MCP server
pip install "podcast-generator[briefing]" # plus narrated briefings (PDF to MP4)Extras combine: pip install "podcast-generator[mcp,briefing]".
The PyPI name is podcast-generator, with a hyphen; the Python package
is podcast_generator, with an underscore. A virtual environment is
recommended. This pulls in Kokoro and torch (about 2 GB) through
voxport[kokoro]. Torch's default build runs on the CPU, so no GPU or
special torch install is needed. Check the install:
podcast-generator --versionNot installed for you:
ffmpeg: needed for MP3 output unless your
soundfile/libsndfile build has native MP3 support. Put it onPATH. WAV output needs neither. Narrated briefings always need it, with H.264 support (libx264), which the usual builds include.Kokoro model weights and spaCy's
en_core_web_sm: downloaded automatically on the first run.
Behind a corporate firewall or proxy, or on a work computer that blocks
new programs? The manual covers
firewalls and proxies
(certificate errors, blocked downloads),
offline use,
and
managed computers
(installing into an existing environment, and python -m instead of the
.exe commands).
From a source checkout
git clone https://github.com/brienalkire/podcast_generator.git
cd podcast_generator
python -m venv .venv
.venv\Scripts\activate # Windows (bash: source .venv/bin/activate)
pip install -e ".[mcp]" pytestWorking on voxport at the same time? Clone it next to this repo and run
pip install -e "../voxport[kokoro]" afterwards.
Related MCP server: mcp-podcast-generator
Where things live
Settings and the default folders live in one home folder:
Install | Home folder |
|
|
Source checkout | the repo folder |
Either |
|
It holds .env (settings), inputs/ (scripts waiting to be converted),
outputs/ (finished audio), script_archive/ (converted scripts, and
failed/ for ones that didn't convert), and generator.log.
The three folders can point anywhere. Use the Podcast Watch app, or set
PODCAST_INPUTS_DIR, PODCAST_OUTPUTS_DIR and PODCAST_ARCHIVE_DIR in
.env (see
.env.example).
Pointing them at a cloud-synced folder (Sync.com, Dropbox, OneDrive) lets
you drop a script in from any device and get the audio back the same way.
Usage
Writing a script
A script is a markdown file. Plain paragraphs are spoken. Headers,
**Key:** value metadata lines, horizontal rules, and italic-only lines
are stripped, so you can label sections and add notes without them being
read aloud:
# My Episode Title
**Voice:** af_heart
## OPENING
Welcome back to the show. Today we're talking about...
## CLOSING
That's all for this episode. Thanks for listening.
---
*Source: some-article.com, September 2026.*Only the two paragraphs are spoken. An italic-only line after the prose starts ends the script, and everything after it is dropped. Keep those lines for trailing notes. See the manual for the full rules.
Conversations with two or more speakers work too. Add a line like
**Voices:** Maya=af_heart, Theo=bm_george and start each spoken line with
the speaker's name (Maya: Welcome back.). Each speaker is read in their
own voice, with a short pause between turns. See
Two or more speakers.
Narrated briefings: the easiest way is to ask Claude Desktop, with the
connector, for "a narrated briefing video of this paper": it builds the
slides as a PDF, writes the narration and makes the video. To do it
yourself, add **Briefing:** deck.pdf and a ## Page N
line before each page's narration, and the script makes an MP4 that shows
each page while it's read. Needs pip install "podcast-generator[briefing]"
and ffmpeg. Narration already in PowerPoint speaker notes?
podcast-generator --extract-notes deck.pptx writes the script for you. See
Narrated briefings.
Pronunciation fixes: put lines like JADC2 = J A D C two in
lexicon.txt in the home folder, and every script says them that way. A
script can add its own with a **Lexicon:** terms.txt line. See
Pronunciation fixes.
Running it
podcast-generator # batch: every script in inputs/
podcast-generator --voice af_heart --speed 1.1 # batch, overriding voice and speed
podcast-generator my-script.md --format wav --output episode01.wav # one fileBatch mode (no file argument) converts every .md script in the inputs
folder and writes <script-name>.mp3 to the outputs folder. The first run
creates the inputs folder if it doesn't exist. Each script that converts
successfully moves into the archive folder, so re-running doesn't
reprocess it. A script that fails moves to <archive folder>/failed/ with
a .error.txt note, so it isn't retried forever.
Single-file mode converts just the named file. --output only applies
here.
Option | Meaning |
| Kokoro voice for the whole run. Overrides a script's |
| Speaking rate (default |
| Output format (default |
| Output file (single-file mode only). |
| Make a narrated MP4 of a PDF (see below). |
| Print how long a script runs, without saving anything (single-file mode). |
| Extra pronunciation lexicon for this run. |
| Wait for a conversion run already in progress, instead of exiting. |
| Accent override; normally inferred from the voice name. |
| Print the version and exit. |
Voice precedence: --voice, then the script's **Voice:** line, then
af_heart.
Drop-folder mode and the Podcast Watch app (Windows)
Running podcast-generator with no arguments on a schedule is watch
mode: each run converts whatever is new in the inputs folder and archives
it. A run with nothing to do exits almost immediately, and only one
conversion runs at a time.
The Podcast Watch app sets this up and controls it:
podcast-watch # open the app
podcast-watch --shortcut # add a "Podcast Watch" shortcut to your desktopSet up watch registers a Windows scheduled task,
PodcastGeneratorWatch, for your user (no admin rights). It runs the converter withpythonw.exe, so no window flashes up; output goes togenerator.login the home folder.Turn ON / Turn OFF enables or disables it; Check every sets the interval (5 to 60 minutes).
When this app opens can always turn the watch on or off when you open the window.
Folders picks the inputs, outputs and archive folders.

To remove the task: Unregister-ScheduledTask -TaskName PodcastGeneratorWatch
in PowerShell. On macOS or Linux, schedule podcast-generator with cron or
a similar tool instead.
Using it from Claude Desktop (MCP)
podcast-generator-mcp is an MCP server,
so an AI app such as Claude Desktop can make podcasts directly: write a
script, queue it, convert it, and check on it, all from the chat. With the
briefing extra it makes narrated briefing videos the same way. It runs
locally and uses the same folders and .env as everything else.
Install it somewhere that stays put. A uv or pipx tool install works well:
uv tool install "podcast-generator[mcp]"Use
"podcast-generator[mcp,briefing]"for briefings too. (pipx install "podcast-generator[mcp]"is the same. A virtual environment works too, as long as you don't delete it.)Print the Claude Desktop config for that install:
podcast-generator-mcp --configIt gives the command's full path, which Claude Desktop needs because it doesn't see your shell's
PATH.In Claude Desktop, open Settings → Developer → Edit Config, merge that
"podcast-generator"entry intomcpServers, and fully quit and restart Claude Desktop (on Windows, quit from the system tray). It then appears in the chat box's connectors menu.
See the manual for checking it's installed, example requests, the tools, and upgrading (quit Claude Desktop first).
Examples
The repository's
examples/
folder has the PDF and narration script behind the
introductory video,
so you can rebuild it yourself, and a sample single-speaker podcast script
explaining a research paper. They aren't part of the pip install; download
them from GitHub. Its
README
has the commands.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Personal podcast queue and private RSS feed managed through a bounded MCP tool set.
Create, import, and publish Jellypod podcast episodes from your AI assistant.
Turn articles and text into narrated audio, playlists and podcast feeds from your AI agent.
1Make podcasts, video shows, audio drama, and documentaries just by chatting. Script to episode.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal podcast transcription, embedding, and semantic search with an MCP server for AI assistant integration. All processing runs on your machine.MIT
- FlicenseNot gradedqualityBmaintenanceGenerates podcast audio from scripts using Google Gemini TTS, supporting single-host monologue and dual-host dialogue with optional intro/outro music and EBU R128 loudness normalization.-
- AlicenseNot gradedqualityAmaintenanceCaptures AI conversation summaries, converts them to Markdown posts, and manages local or remote publishing with metrics tracking.MIT
- FlicenseNot gradedqualityBmaintenanceEnables generating finished MP3 podcast audio from scripts using local TTS engines, with configurable voices and speech speed, plus text-to-speech and voice listing tools.-