Chalkcast

Chalkcast

Describe a concept. Get a *verified* animated explainer.

Chalkcast is an MCP server that lets an agent author, render, and visually verify Manim animations — so the output is a video that's actually correct on screen, not a plausible script that renders wrong.

One continuous animation, authored, verified and rendered entirely through the MCP server (passed on the first render): a Fourier series grows harmonic by harmonic into a square wave, and the Gibbs overshoot (the true one, ≈ 1.179) stays at the edges. Reproduce it with python examples/showcase.py .

---

Who it's for

• Educators & students — turn "explain the Fourier series" into a clean animated explainer, without learning Manim or writing LaTeX by hand.
• STEM content creators — produce 3Blue1Brown-style animations in minutes instead of hours of coding and debugging renders.
• Agents & tooling — a typed, verifiable MCP surface an AI can drive end to end, with a verdict it can act on instead of a video it can't inspect.

Why another Manim MCP?

Existing Manim MCP servers give the agent one tool: *run this code, return the video.* The agent writes Manim blind and hopes — but Manim is unforgiving (a LaTeX typo, an off-screen label, two terms overlapping, a transition firing before its target exists). The video "renders" and is still wrong, and the agent has no way to know.

Chalkcast gives the agent eyes and a correction loop:

author scene ──► render ──► inspect (verification lanes) ──► verdict

▲ │ └──────────────── fix obligations ◄──── needs_fix ─────────┘

Every render returns evidence (the artifact + sampled frames) and a structured verdict. Problems become obligations that block export until resolved. See docs/SPEC.md for the full design.

Install

One command (Claude Code; needs uv):

claude mcp add chalkcast -- uvx --python 3.12 --from "chalkcast[render]" chalkcast serve

--python 3.12 matters: Chalkcast needs Python ≥ 3.11, and uv downloads one if the system Python is older (macOS ships 3.9). Then just ask in natural language.

Or with pip, into any Python ≥ 3.11 environment:

pip install "chalkcast[render]"

claude mcp add chalkcast -- chalkcast serve

[render] brings Manim and a bundled ffmpeg. Equations also need a LaTeX distribution. chalkcast doctor checks everything and prints the exact fix command for your OS:

chalkcast doctor               # Manim / LaTeX / dvisvgm / physics.sty / ffmpeg

chalkcast demo # builds + verifies + renders the demo scene

macOS: pycairo (pulled in by Manim) has no macOS wheel and builds from

source, so it needs brew install cairo pkg-config first. On a machine where

Manim's native deps were built by hand, see scripts/dev-env.sh and

scripts/serve.sh.

What the agent gets

• Continuous animation: add_parameter("t"), use t in plot expressions or shape anchors (at_x="t"), then add_step("tween", param="t", value=6.28). Curves, areas and anchored dots follow it frame by frame. with_previous=True plays a step at the same time as the one before.
• Fail fast, nothing implicit: expressions are validated when authored (an AST whitelist: x, math functions, np. , declared parameters). Colors, ranges, step targets, timeline order, and arguments that don't apply to a shape or step are rejected with a message saying what to do. Edits are all-or-nothing. Side effects (cascade removals, regrouped steps, redeclared parameters, default ranges) are reported in the result. export_gif refuses a render that predates the latest edit. Thirty-two independent audits (22, then 17, 14, 8, 4, 9, 4, 7, 5, 5, 7, 8, 5, 8, 7, 7, 10, 4, 5, 5, 8, 7, 7, 5, 7, 9, 7, 4, 10, 9, 7 and 6 findings, the last with no high-severity one; in the last thirteen, 9, 10, 8, 10, 9, 9, 9, 9, 9, 10, 8, 9 and 10 of 10 fresh explainers reached a correct GIF within two renders, and in the last one every verdict matched its frames; the last twenty-three built realistic explainers end to end and compared verdicts with frames, one of them over the real MCP stdio protocol) are pinned one test per finding in tests/test_ergonomics.py.
• Faithful plots: dense sampling, curves split at jumps and poles (no invented risers or overshoot), clipping to the axes. A *fidelity* lane measures the drawn curve against the true function. Areas and Riemann sums are refused when they could not show the integral (function undefined or off the axes, y = 0 not visible).

How verification works

inspect_render builds the real Manim objects without encoding video (1–3 s) and measures them: exact bounding boxes, curve and axis ink, the drawn-vs-true error of every graph, and a strict LaTeX compile (Manim's batch mode silently "recovers" from LaTeX errors). Lanes: framing · collision · legibility · timing · compile · fidelity · range. fix_scene repairs the mechanical problems (moves, rescales, resampling) and leaves the rest as obligations for the agent.

Measured on labelled scenes (chalkcast bench, chalkcast bench --holdout N). Each held-out set was written and labelled (and checked frame by frame) by an author who never read the verifier. The first run of each set is the honest out-of-sample figure:

After each set's bugs were fixed, every set (and the 40-case development set) scores 100 % / 0 %. From then on they are regression tests (tests/test_measured.py), not independent measures. Held-out 3 was written after the fixes for sets 1 and 2, and held-out 4 (continuous tweens, simultaneous beats, transforms, camera moves) after eleven ergonomics audits; each was run once, untouched. Held-out 4 is the current out-of-sample estimate.

Example (what the agent does)

open_project(theme="chalkboard")

add_scene(title="Area under a parabola") add_text("Area under y = x^2", y=3) add_plot(functions=[{"expr":"x**2","color":"YELLOW"}], x_range=[0,2,1], y=-0.8) add_equation(r"\int_0^1 x^2 \, dx = \tfrac{1}{3}", y=2) add_step("write", targets=["text_1"]) add_step("write", targets=["plot_1"]) add_step("write", targets=["equation_1"]) add_step("highlight", targets=["equation_1"]) inspect_render() # -> measured verdict in ~2 s, no video fix_scene() # -> repairs framing / collision / fidelity if needed render_scene() # -> video + frames + verdict + obligations export_gif() # -> shareable GIF (blocked if error obligations remain)

Status

Alpha. Scientific correctness is tested numerically (tests/test_science.py): shaded areas equal their integrals, Riemann rectangles their sum, drawn curves their function (including sin 30x), and the Gibbs peak its theoretical value. On PyPI and the MCP Registry (io.github.FredMichel/chalkcast). Vision-based intent verification is next (see docs/SPEC.md).

License

MIT.