mcp-video-pipeline_2 0.1.1

MCP server for generating algorithm explanation videos

AI Video Pipeline — MCP Server

This pipeline helps you make algorithm-explanation videos with minimal manual work. Claude Desktop calls these tools automatically — you just describe your video idea and follow the steps.

---

🗺️ How the Pipeline Works

Your Idea (topic + gist)
       │
       ▼
  [Tool 1] Script Generator       ← Claude writes your full narration script
       │
       ▼
  You record the voiceover
  Premiere Pro → export timestamped transcript
       │
       ▼
  [Tool 2] Scene Planner          ← splits transcript into visual scenes
       │
       ├── for image scenes →
       │   [Tool 3] Image Prompt Generator  ← paste into Whisk / Midjourney
       │
       └── for animation scenes →
           [Tool 4] Animation Generator     ← generates Manim Python code

---

📋 Prerequisites

Before starting, you need:

Requirement	How to get it
Python 3.10+	python.org/downloads
Claude Desktop	claude.ai/download
Free Gemini API key	aistudio.google.com/apikey — no credit card
Premiere Pro (for transcripts)	Any version with SRT caption export
(Optional) Manim	Only if you want equation animations — install separately

---

🚀 Setup (Step by Step)

Step 1 — Clone / Download the Project

Put the mcp_video_pipeline folder somewhere easy to find.
Example location: C:\Proj\DD\mcp_video_pipeline\

---

Step 2 — Install Python Dependencies

Open Command Prompt or PowerShell, then run:

cd C:\Proj\DD\mcp_video_pipeline
pip install -r requirements.txt

You should see packages being downloaded. This takes 1-2 minutes.

---

Step 3 — Get Your Free Gemini API Key

1. Go to: https://aistudio.google.com/apikey
2. Sign in with your Google account.
3. Click "Create API Key".
4. Copy the key (it looks like: AIzaSy...).

Free limits: 15 requests/minute, 1 million tokens/day. More than enough for video production.

---

Step 4 — Set Up Your API Key

In the mcp_video_pipeline folder:

1. Find the file called .env.example
2. Make a copy of it and name the copy exactly: .env (just dot-env, no .example)
3. Open .env in Notepad and replace your_free_gemini_api_key_here with your actual key

GEMINI_API_KEY=AIzaSyYOUR_ACTUAL_KEY_HERE

Save the file.

---

Step 5 — Configure Claude Desktop

1. Open the file claude_desktop_config.json (in this project folder) — it shows you what to copy.

2. Find Claude Desktop's config file:

   • Windows: Press Win+R, type %APPDATA%\Claude\, press Enter
   • Open claude_desktop_config.json in Notepad (create it if missing)

3. Your config file should look like this — add the mcpServers block:

{
  "mcpServers": {
    "ai-video-pipeline": {
      "command": "python",
      "args": ["C:\\Proj\\DD\\mcp_video_pipeline\\server.py"]
    }
  }
}

⚠️ Important: Update the path if your project is in a different location.
Use double backslashes \\ in the path (this is a Windows JSON requirement).

4. Save the file.

5. Fully quit and restart Claude Desktop (right-click the tray icon → Quit, then reopen).

---

Step 6 — Verify It's Working

In Claude Desktop, look for a 🔧 tools icon (hammer icon) in the chat bar.
Clicking it should show 4 tools:

• generate_script
• plan_scenes
• generate_image_prompt
• generate_animation_code

If you don't see them: see the Troubleshooting section below.

---

🎬 Using the Pipeline

Stage 1: Generate Your Script

Tell Claude something like:

"I want to make a video about Dijkstra's shortest path algorithm. The tagline is 'How GPS knows the fastest route.' The gist is: Dijkstra's finds the cheapest path in a weighted graph. It's used in GPS and internet routing. Make it 10 minutes."

Claude will call the generate_script tool and return:

• Full narration script
• Key equations used
• Metaphors used

Review the script. Make edits if needed.

---

Stage 2: Record & Transcribe (You Do This)

1. Record yourself reading the script naturally.
2. In Premiere Pro:
   • Go to Window → Text → Transcript
   • Click "Transcribe Sequence"
   • Once done, export as SRT or copy the text with timestamps
3. Format: [HH:MM:SS] spoken words... per line

---

Stage 3: Plan Your Scenes

Paste the transcript and tell Claude:

"Here is my transcript: [paste transcript here]. Plan the scenes for me."

Claude calls plan_scenes and returns a table of scenes with timestamps, descriptions, and types (image or animation).

---

Stage 4: Generate Visuals

For each image scene, Claude automatically calls generate_image_prompt.
You get a ready-to-paste prompt for Whisk, Midjourney, Firefly, or any image AI.

For each animation scene, Claude calls generate_animation_code.
You get a Python file. To render:

pip install manim
manim -pql animation_scene.py YourSceneName

---

🔧 Troubleshooting

Problem	Fix
Tools not showing in Claude Desktop	Check the path in claude_desktop_config.json is correct. Fully restart Claude (not just close window).
GEMINI_API_KEY is not set error	Make sure your .env file exists (not .env.example) and the key is correct.
pip: command not found	Install Python from python.org and check "Add to PATH" during install.
429 Rate Limit error	You've sent 15 requests in under a minute. Wait 60 seconds and retry.
Manim LaTeX error	Install MiKTeX from miktex.org (Windows). Required for equation rendering.
JSON parse error in tools	Retry — occasionally Gemini may return slightly malformed JSON. Rare.

---

📁 Project File Map

mcp_video_pipeline/
├── server.py                    ← MCP server entry-point (start here to understand the project)
├── requirements.txt             ← Python packages
├── .env.example                 ← Copy → .env and add your Gemini key
├── claude_desktop_config.json   ← Snippet for Claude Desktop setup
├── README.md                    ← This file
├── tools/
│   ├── script_generator.py      ← Tool 1: Video script generation
│   ├── scene_planner.py         ← Tool 2: Transcript → scene list
│   ├── image_prompt_generator.py ← Tool 3: Scene → AI image prompt
│   └── animation_generator.py   ← Tool 4: Scene → Manim Python code
└── utils/
    ├── model_client.py          ← Gemini API calls (shared by all tools)
    └── schemas.py               ← Data validation models

---

🤖 Free Model Details

Detail	Value
Model	gemini-2.0-flash
Provider	Google AI Studio
Cost	Free
Rate limit	15 requests/minute
Daily limit	1,000,000 tokens/day
Context window	1,000,000 tokens
API key required	Yes (free, no credit card)

To switch models, edit the GEMINI_MODEL line in your .env file.

---

✅ Testing Without Claude Desktop (Developer Mode)

cd C:\Proj\DD\mcp_video_pipeline
mcp dev server.py

Open http://localhost:5173 in your browser. You'll see the MCP Inspector — a UI to test each tool individually with sample inputs.