Manim MCP Server

# Manim MCP Server A Model Context Protocol (MCP) server that enables Claude Desktop to create mathematical animations using [Manim](https://www.manim.community/) (Mathematical Animation Engine). This server allows Claude to generate video artifacts of mathematical explanations, making it easy to visualize complex mathematical concepts through animations. ## Features - **Create Math Animations**: Generate mathematical animations by providing Manim scene code - **Multiple Quality Options**: Render videos in low (480p), medium (720p), or high (1080p) quality - **Example Templates**: Get example code for common animation types (equations, graphs, geometry, etc.) - **Easy Integration**: Works seamlessly with Claude Desktop through MCP ## Installation ### Option 1: MCPB Bundle (Easiest - One-Click Install) **For end users - Recommended!** 1. Download the latest `.mcpb` file from [Releases](https://github.com/Stelath/manim-mcp/releases) 2. Double-click the `.mcpb` file (or drag-and-drop into Claude Desktop) 3. Follow the installation prompts in Claude Desktop 4. Install system dependencies (see below) **MCPB bundles provide:** - ✅ One-click installation in Claude Desktop - ✅ No manual configuration required - ✅ Automatic updates - ✅ Easy uninstall **Building MCPB yourself:** See [MCPB_BUILD.md](MCPB_BUILD.md) for instructions on creating your own `.mcpb` bundle. ### Option 2: Direct Install (For Developers) **Install from GitHub** ```bash pip install git+https://github.com/Stelath/manim-mcp.git ``` **Install from Local Clone** ```bash git clone https://github.com/Stelath/manim-mcp.git cd manim-mcp ./install.sh # On macOS/Linux # OR install.bat # On Windows ``` **Using uvx (Isolated environments)** ```bash uvx --from git+https://github.com/Stelath/manim-mcp.git manim-mcp ``` This will install: - `manim-mcp` - The MCP server command - `manim` - The Manim Community Edition library - `mcp` - The Model Context Protocol SDK ### Prerequisites - Python 3.10 or higher - [Claude Desktop](https://claude.ai/download) ### Additional System Dependencies Manim requires some system dependencies. Install them based on your OS: **macOS:** ```bash brew install py3cairo ffmpeg brew install --cask mactex-no-gui ``` **Ubuntu/Debian:** ```bash sudo apt-get update sudo apt-get install build-essential python3-dev libcairo2-dev libpango1.0-dev ffmpeg sudo apt-get install texlive texlive-latex-extra ``` **Windows:** - Install [Chocolatey](https://chocolatey.org/) - Run: `choco install manimce` For detailed installation instructions, see the [Manim installation guide](https://docs.manim.community/en/stable/installation.html). ## Configuration ### MCPB Users (Option 1) **No manual configuration needed!** The `.mcpb` bundle handles configuration automatically. ### Manual Configuration (Option 2 - For Direct Install Only) If you installed via pip/uvx, add this server to your Claude Desktop configuration file: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` **Linux:** `~/.config/Claude/claude_desktop_config.json` Add the following to your configuration: ```json { "mcpServers": { "manim": { "command": "manim-mcp" } } } ``` That's it! Just one line. No paths, no environment variables needed. **Alternative: Using uvx (for direct GitHub installation without pip)** ```json { "mcpServers": { "manim": { "command": "uvx", "args": [ "--from", "git+https://github.com/Stelath/manim-mcp.git", "manim-mcp" ] } } } ``` ### Restart Claude Desktop After updating the configuration, restart Claude Desktop for the changes to take effect. ## Usage Once configured, you can ask Claude to create mathematical animations. Here are some examples: ### Example 1: Simple Text Animation ``` Create a Manim animation that displays "Hello, Mathematics!" and then fades out. ``` ### Example 2: Mathematical Equation ``` Create a Manim animation showing Euler's identity: e^(iπ) + 1 = 0 Animate the equation being written, then highlight it. ``` ### Example 3: Graph Visualization ``` Create a Manim animation of a sine wave being drawn on a coordinate system, with the equation y = sin(x) labeled. ``` ### Example 4: Geometric Transformation ``` Create a Manim animation showing a circle transforming into a square, then into a triangle, demonstrating geometric morphing. ``` ### Example 5: Calculus Visualization ``` Create a Manim animation showing the area under the curve y = x^2 from 0 to 2, illustrating the concept of integration. ``` ## Available Tools The server exposes the following MCP tools: ### `create_math_animation` Create and render a mathematical animation. **Parameters:** - `scene_code` (required): Python code defining a Manim Scene class - `scene_name` (required): Name of the Scene class to render - `quality` (optional): Render quality - "low", "medium" (default), or "high" - `output_filename` (optional): Custom filename for the output video **Returns:** Path to the generated video file ### `get_manim_example` Get example Manim code for common animation types. **Parameters:** - `example_type` (required): One of: - `basic_text` - Simple text animation - `equation` - Mathematical equation - `graph` - Function graph - `geometry` - Geometric shapes - `transformation` - Shape transformations - `calculus` - Calculus visualization **Returns:** Example code and usage instructions ## Output Location Generated videos are saved to: `{system_temp_dir}/manim_mcp_output/` - **macOS/Linux:** `/tmp/manim_mcp_output/` - **Windows:** `C:\Users\{username}\AppData\Local\Temp\manim_mcp_output\` ## Troubleshooting ### Server Not Appearing in Claude Desktop 1. Check that the configuration file path is correct 2. Verify the Python path in the configuration 3. Restart Claude Desktop completely 4. Check Claude Desktop logs for errors ### Manim Rendering Errors 1. Ensure all system dependencies are installed (ffmpeg, LaTeX, Cairo) 2. Test Manim independently: `manim --version` 3. Check the error messages returned by the tool ### Import Errors 1. Verify the package is installed: `pip show manim mcp` 2. Check that PYTHONPATH includes the `src` directory 3. Try reinstalling: `pip install -e . --force-reinstall` ## Development ### Building MCPB Bundles To create a `.mcpb` bundle for distribution: 1. **Install MCPB CLI:** ```bash npm install -g @anthropic-ai/mcpb ``` 2. **Ensure icon.png exists** (512x512 PNG file) 3. **Build the bundle:** ```bash ./build_mcpb.sh # macOS/Linux # OR build_mcpb.bat # Windows # OR mcpb pack # Direct CLI ``` 4. **Test the bundle:** - Double-click the generated `.mcpb` file - Or drag-and-drop into Claude Desktop - Verify both tools work correctly For complete build instructions, see [MCPB_BUILD.md](MCPB_BUILD.md). ### Project Structure ``` manim-mcp/ ├── manifest.json # MCPB manifest ├── icon.png # Extension icon ├── src/ │ └── manim_mcp/ │ ├── __init__.py │ ├── __main__.py │ └── server.py # Main MCP server implementation ├── pyproject.toml # Package configuration ├── README.md ├── MCPB_BUILD.md # MCPB build guide └── LICENSE ``` ### Running Tests ```bash pytest ``` ### Code Formatting ```bash black src/ ruff check src/ ``` ## Learn More - [Manim Community Documentation](https://docs.manim.community/) - [MCP Documentation](https://modelcontextprotocol.io/) - [Claude Desktop](https://claude.ai/) ## License See [LICENSE](LICENSE) file for details. ## Contributing Contributions are welcome! Please feel free to submit issues or pull requests. ## Credits - [Manim Community](https://www.manim.community/) - Mathematical Animation Engine - [Anthropic](https://www.anthropic.com/) - Model Context Protocol and Claude - [3Blue1Brown](https://www.3blue1brown.com/) - Original Manim creator