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.<fn>, 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. Twelve independent audits (22, then 17, 14, 8, 4, 9, 4, 7, 5, 5, 7 and 8 findings; the last three built 34 realistic explainers end to end and compared verdicts with frames) 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.