manim-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# manim-mcp
+
+MCP server that generates 3Blue1Brown-style math animation videos with [Manim](https://www.manim.community/) directly inside Claude. Videos render with AI-narrated voiceover and play inline in the chat.
+
+## Quick Start
+
+### 1. Add to Claude Desktop
+
+Open **Settings > Developer > Edit Config** and add:
+
+```json
+{
+  "mcpServers": {
+    "manim": {
+      "command": "npx",
+      "args": ["-y", "manim-mcp@latest", "--stdio"]
+    }
+  }
+}
+```
+
+### 2. Restart Claude Desktop
+
+That's it. Ask Claude to "create a video explaining the Pythagorean theorem" and watch it render.
+
+**First run** takes ~2 minutes to auto-install Python dependencies, TTS models, and LaTeX. Subsequent runs are fast.
+
+## Features
+
+- **Multi-scene video generation** with parallel rendering and scene-level caching
+- **AI voiceover narration** synced to animations (Kokoro TTS, runs 100% locally)
+- **20+ language support** — English, Chinese, Japanese, Spanish, French, Hindi, and more
+- **Built-in video player** renders inline in Claude Desktop
+- **Comprehensive Manim reference library** produces high-quality 3b1b-style animations
+- **Speculative TTS pre-synthesis** — voiceovers are generated while scenes render
+- **Auto-fixes** common Manim code mistakes before rendering
+
+## How it Works
+
+```
+You: "create a video on eigenvalues"
+
+Claude:
+  1. Loads Manim reference guidelines (get_manim_reference)
+  2. Plans 2-4 scenes with narration scripts
+  3. Writes Manim Python code for each scene
+  4. Calls render_video with all scenes
+     -> TTS pre-synthesizes all voiceovers
+     -> scenes render in parallel
+     -> concatenated into one video
+  5. Inline video player appears in chat
+```
+
+## Requirements
+
+- **Node.js 18+** — for running the MCP server
+- **Python 3.12+** — for Manim rendering (auto-installed into `~/.manim-mcp/.venv`)
+- **ffmpeg** — for video concatenation (`brew install ffmpeg` on macOS)
+
+Everything else (Manim, voiceover, TTS models, LaTeX) is automatically installed on first run.
+
+### Optional: Premium Voice
+
+For premium multi-language voiceover via ElevenLabs, add your API key:
+
+```json
+{
+  "mcpServers": {
+    "manim": {
+      "command": "npx",
+      "args": ["-y", "manim-mcp@latest", "--stdio"],
+      "env": {
+        "ELEVEN_API_KEY": "sk_your_key_here",
+        "PREFER_ELEVENLABS": "1"
+      }
+    }
+  }
+}
+```
+
+## Language Support
+
+| Engine | Languages | Notes |
+|--------|-----------|-------|
+| Kokoro (default) | English, Chinese, Japanese, Spanish, French, Hindi, Italian, Portuguese | Local, fast, free |
+| Piper | German, Russian, Dutch, Polish, Czech, Turkish, Arabic, Hungarian | Local, free |
+| ElevenLabs | All languages | Requires API key |
+
+## Development
+
+```bash
+git clone https://github.com/zcsabbagh/manim-mcp.git
+cd manim-mcp
+npm install
+npm run build
+
+# Point Claude Desktop at local build:
+# "command": "node",
+# "args": ["/path/to/manim-mcp/dist/index.js", "--stdio"]
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+// main.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import { createServer } from "./server.js";
+async function startStreamableHTTPServer(createServerFn) {
+  const port = parseInt(process.env.PORT ?? "3001", 10);
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  app.use(cors());
+  app.all("/mcp", async (req, res) => {
+    const server = createServerFn();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0
+    });
+    res.on("close", () => {
+      transport.close().catch(() => {
+      });
+      server.close().catch(() => {
+      });
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null
+        });
+      }
+    }
+  });
+  const httpServer = app.listen(port, () => {
+    console.log(`Manim MCP server listening on http://localhost:${port}/mcp`);
+  });
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+async function startStdioServer(createServerFn) {
+  await createServerFn().connect(new StdioServerTransport());
+}
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await startStdioServer(createServer);
+  } else {
+    await startStreamableHTTPServer(createServer);
+  }
+}
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+export {
+  startStdioServer,
+  startStreamableHTTPServer
+};