antoniomachuca/MCP-Manim-Slides

A robust Model Context Protocol (MCP) server that empowers AI agents to generate, orchestrate, and compile interactive presentations with manim-slides.
Overview
While traditional AI coding assistants can write Manim code, executing that code and structuring it into a readable presentation format has remained a manual process. This MCP server bridges the gap by providing AI clients (like Claude Desktop, Cursor, or Antigravity) with direct tools to:
1. **Execute Manim Scripts**: Dynamically run generated Manim code safely.
2. **Handle Slides Orchestration**: Natively support the Slide class for presentation logic.
3. **Compile Presentations**: Convert rendered animations into interactive HTML presentations (Reveal.js) directly from the AI prompt.
Demo
Features
- **Direct Code Execution**: Send Python code containing Manim Slide classes; the server handles temporary file creation, execution, and cleanup.
- **Error Feedback Loop**: Captures standard output and runtime exceptions, feeding them back to the AI for autonomous debugging.
- **Live Render Progress**: Streams rendered-frame percentage updates to the client via notifications/progress.
- **Slide-Archetype Prompt Templates**: Built-in MCP prompts (title_slide, agenda, code_walkthrough, math_derivation, two_column_comparison) that turn a few arguments into detailed instructions for writing well-laid-out Manim-Slides code.
- **Per-Scene Render Caching**: Content-hashes each scene class (preamble + class source + quality) so editing one scene never re-renders its siblings, reusing previously rendered media from .render_cache.
- **Incremental Deck Sync**: sync_deck renders only new or changed scenes, restores the rest from cache, reports removed scenes, and recompiles the deck in one call.
- **HTML/Reveal.js Export**: Seamlessly compiles the generated video assets into a fully functional interactive web presentation.
- **Single-MP4 Export**: export_video stitches all slide media into one MP4 via FFmpeg, with optional crossfade transitions and fixed-duration handling for still-image slides.
- **Deck Screenshots & Contact Sheets**: screenshot_deck captures every slide headlessly (optional Playwright vision extra) so the AI can see its own deck, and contact_sheet montages slide frames into a single grid image using FFmpeg only.
- **One-Click Browser Preview**: Serves the exported Reveal.js HTML on an ephemeral local HTTP server so it can be opened in a browser with a single call.
- **State Management**: Persists generated media in structured workspace directories for easy access.
Prerequisites
Ensure your system has the following installed:
- Python 3.10+
- uv (dependency and environment management)
- Manim Community Edition (Requires FFmpeg and LaTeX)
- Manim-Slides
Installation
The vision extra (or pip install "mcp-manim-slides[vision]" for pip users) adds Playwright, which screenshot_deck needs to capture deck slides headlessly; run playwright install chromium once afterwards to download the browser binary. Every other tool — rendering, caching, syncing, compiling, exporting video, and contact sheets — works without it.
Configuration
To integrate this server with an MCP-compatible client (e.g., Claude Desktop, Cursor, Antigravity), add the following to your client configuration JSON:
Available MCP Tools & Resources
Tools (@mcp.tool)
- hello_world(name: str = "World"): Connectivity check tool to verify client-server MCP communication.
- execute_manim_code(code: str, scenes: list[str] | None = None, quality: str = "l", media_dir: str | None = None, timeout: int = 600, use_cache: bool = True): Writes the provided Manim code to a secure temporary script, renders the scenes headlessly via manim-slides render, and returns paths to produced media files. Caches rendered output per scene by a content hash of the shared preamble, the scene class source, and quality, so editing one scene never invalidates its siblings; only changed scenes are re-rendered unless use_cache=False.