# abhiemj/manim-mcp-server architecture

> Architecture diagram of the GitHub repository abhiemj/manim-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhiemj/manim-mcp-server
- Repository: https://github.com/abhiemj/manim-mcp-server

## Overview

##### Project Type and Purpose
- This is a single‐service backend (an MCP server) whose sole responsibility is to take incoming Manim animation scripts (via the Model Context Protocol), execute them using the Manim CLI, and return the rendered video. There is no separate “frontend” in this repo; it is intended to be plugged into an MCP‐aware client (e.g., Claude).

##### High‐Level Components
a. MCP Client
- Any application or tool (e.g., Claude) that speaks the MCP protocol and needs to generate animations.
b. Manim MCP Server (manim_server.py)
- The Python process that receives MCP messages on stdin/stdout (or via whatever transport MCP uses), parses requests, and orchestrates execution.
c. Manim CLI
- The external “manim” executable (configured via the MANIM_EXECUTABLE env var) that actually renders the scene.
d. File System / Media Folder
- Temporary folder(s) where scripts are written, intermediate frames are stored, and final videos are saved.
e. Cleanup Module
- Logic inside manim_server.py to remove temp files on demand (another MCP command).

##### Component Interactions
- The MCP Client sends a JSON‐RPC–style request to the Manim MCP Server (over stdio).
- manim_server.py writes the received script into a .py file under a temp directory.
- manim_server.py spawns the Manim CLI subprocess, passing appropriate args (scene name, output directory).
- Manim CLI renders frames and encodes them into a video file in the media folder.
- The server watches for process completion, then reads back the video path (or base64 content) and returns it as an MCP response.
- If a “cleanup” command arrives, the server deletes the temp directory and media outputs.

##### Architectural Patterns and Principles
- Single‐Responsibility Microservice: this component only handles Manim code execution.
- External Process Invocation: clear boundary between Python orchestration and the Manim binary.
- Configurable via Environment Variables: MANIM_EXECUTABLE, temp/media directory paths, etc.
- Protocol Abstraction: MCP layer decouples this server from any particular client; uses stdin/stdout JSON messaging.

##### Technologies, Frameworks, Libraries
- Python 3.8+: runs the manim_server.py script, uses the “subprocess” module.
- Manim Community Edition: rendering engine, invoked as an external CLI.
- MCP (Model Context Protocol): lightweight IPC protocol over stdio or other transports.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Client["MCP Client"]:::client
    subgraph "Deployment Container"
        MSS["Manim MCP Server\n(request parsing, orchestration,\ncleanup logic)"]:::python
    end
    CLI["Manim CLI\n(MANIM_EXECUTABLE)"]:::external
    FS[(Media & Temp Folder)]:::fs

    %% Connections
    Client -->|"MCP Request\n(script + params)"| MSS
    MSS -->|"write .py & config"| FS
    MSS -->|"spawn process (manim ...)"| CLI
    CLI -->|"write video.mp4"| FS
    MSS -->|"MCP Response\n(video path or data)"| Client
    Client -->|"cleanup temp files"| MSS

    %% Click events
    click MSS "https://github.com/abhiemj/manim-mcp-server/blob/main/src/manim_server.py"

    %% Styles
    classDef python fill:#cce5ff,stroke:#000
    classDef external fill:#d4edda,stroke:#000
    classDef fs fill:#e2e3e5,stroke:#000
    classDef client fill:#ffe5b4,stroke:#000
    class MSS python
    class CLI external
    class FS fs
    class Client client
```
