Animated Explainers MCP
README.md
# Animated explainer videos from a chat
The full guide: [Animated explainer videos from a chat, on an ordinary computer](https://vollendata.com/studio/animated-explainers-mcp/). Example videos: [why the sky is blue](https://youtu.be/9834QMk9-mw) and [black holes in a minute](https://youtu.be/may009OOnxM).
A small [MCP](https://modelcontextprotocol.io/) server that lets Claude turn a topic into a narrated, animated explainer video. It runs on the processor of an ordinary computer: no graphics card, no paid API and no other AI service.
Each scene is an animated web page with a heading and up to four points. Playwright records the page frame by frame, ffmpeg turns the frames into video, and [Piper](https://github.com/OHF-Voice/piper1-gpl) reads the narration. On the test machine a 27 to 31 second, two-scene video took 105 to 125 seconds to make, with nothing running on the graphics card.
[example/why-is-the-sky-blue.mp4](example/why-is-the-sky-blue.mp4) is a 31 second video that Claude Code made through this server from the request "explain why the sky is blue for a ten year old".

## What it needs
- [Claude Code](https://code.claude.com/), or another MCP client
- Python 3.10 or later
- [ffmpeg](https://ffmpeg.org/) on the PATH
- About 200 MB of downloads: Playwright's Chromium (about 124 MB) and one Piper voice (about 63 MB)
## Set it up
macOS or Linux:
```bash
git clone https://github.com/randallvollen-boop/animated-explainers-mcp.git
cd animated-explainers-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m playwright install chromium
.venv/bin/python -m piper.download_voices en_US-ljspeech-medium --download-dir voices
```
Windows (PowerShell): the same steps with `.venv\Scripts\python.exe` and `.venv\Scripts\pip.exe`.
Or open Claude Code in the cloned folder and ask it to do the setup above, asking before any command that needs an administrator password.
Check it works without any chat client:
```bash
.venv/bin/python try_it.py
```
It starts the server the way an MCP client does, asks for a two-scene video about black holes and prints the path of the finished MP4 in `videos/`.
## Connect it to Claude Code
```bash
claude mcp add explainer -- "$PWD/.venv/bin/python" "$PWD/server.py"
claude mcp list
```
Then ask in plain words, for example:
> Use the explainer tools to make a short narrated video, two scenes, explaining why the sky is blue for a ten year old. Keep each narration to two or three sentences. Wait for it to finish by checking video_status every 20 seconds, then tell me the file path.
Claude writes the scenes, calls `make_explainer`, checks `video_status` until the job is done and gives back the file path. Claude cannot watch the video, so watch it before posting it anywhere.
Tested on Linux with Claude Code. Claude Desktop, macOS and Windows were not tested; the Claude Desktop config takes the same command and arguments under `mcpServers`.
## The two tools
| Tool | What it does |
| --- | --- |
| `make_explainer(title, scenes)` | Starts a video and returns a job id at once. Each scene has a `heading`, up to four `points` and the `narration` read during it. |
| `video_status(job_id)` | Reports progress, then the path of the finished MP4. |
A render takes a couple of minutes and an MCP client can time out on one long tool call, so the work starts in the background and is checked separately.
Output: H.264 video at 1280 by 720 and 30 frames per second, with AAC sound. Each scene lasts as long as its narration plus one second.
## Changing it
Ask Claude for changes to `server.py` in plain words: other colours or fonts in `scene_page`, a diagram scene, a different voice, or a vertical 1080 by 1920 frame for Shorts (change `W` and `H`, and the positions inside `scene_page`).
## A note on the MCP SDK
Version 2 of the Python MCP SDK renamed `FastMCP` to `MCPServer` (`from mcp.server.mcpserver import MCPServer`). Tutorials that import `from mcp.server.fastmcp import FastMCP` fail on version 2. This repo pins `mcp==2.3.0`.
## Voices and licences
- The code in this repository is MIT licensed (see [LICENSE](LICENSE)).
- Piper, the speech engine installed by `requirements.txt`, is GPL-3.0-or-later.
- Each Piper voice has its own licence on its [model card](https://huggingface.co/rhasspy/piper-voices). The default here, `en_US-ljspeech-medium`, is trained on the LJSpeech dataset, which its card lists as public domain. Some popular voices, such as Lessac, use research-only datasets, so check the card before publishing videos made with another voice.
## Other routes to animated video
| Route | Good for | How Claude drives it |
| --- | --- | --- |
| [Manim](https://www.manim.community/) | Maths animation and diagrams | Community MCP servers that run Manim scripts |
| [Remotion](https://www.remotion.dev/) | Videos written as React code | An agent skill; free for individuals and teams of up to three, paid for larger companies |
| [Motion Canvas](https://github.com/motion-canvas/motion-canvas) | TypeScript animation with a live editor | Claude writes the scene code (MIT; maintenance status unclear) |
| [Blender MCP](https://github.com/ahujasid/blender-mcp) | 3D scenes | An MCP server driving a live Blender session |
## Related writing
- [Making a first video with Claude, from a web page to a local studio](https://vollendata.com/studio/first-video-with-claude/): how the frame-by-frame recorder works
- [Four tools, any model](https://vollendata.com/writing/four-tools-any-model/): the same start-then-check MCP pattern in front of image and video models
- [Five videos from one MCP](https://vollendata.com/studio/agent-driven-music-videos/): an agent driving a bigger app through its MCP server
By Randall Vollen.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues