Ai Video

Turn text scripts into complete videos with stock footage, AI narration, and subtitles. Standard MCP tool — works with Claude, OpenClaw, Cursor, and any MCP-compatible AI assistant.

smithery Python License

---

✨ Features

• 📝 Script-driven — Just provide text, auto-split into chapters
• 🎥 Smart footage — Auto-matches stock videos from Pexels per chapter
• 🗣️ TTS narration — Minimax voice synthesis, 6 voice options
• 📺 Auto subtitles — Generates SRT subtitles from narration
• 🎬 One-click compose — ffmpeg auto-merges into final video
• 🔌 MCP standard — Compatible with all MCP-enabled AI assistants

---

🚀 Quick Start

1. Install

pip install ai-video-mcp

Or from source:

git clone https://github.com/yqyqstart-crypto/ai-video-mcp.git
cd ai-video-mcp
pip install -e .

2. Set API Keys

export MINIMAX_API_KEY="your-minimax-key"
export PEXELS_API_KEY="your-pexels-key"

Key	Get it from	Purpose
MINIMAX_API_KEY	platform.minimaxi.com	TTS voice synthesis
PEXELS_API_KEY	pexels.com/api	Stock video search

3. Use

Command Line

ai-video-mcp

MCP Config (Claude Desktop / OpenClaw / Cursor)

{
  "mcpServers": {
    "ai-video": {
      "command": "ai-video-mcp",
      "env": {
        "MINIMAX_API_KEY": "your-key",
        "PEXELS_API_KEY": "your-key"
      }
    }
  }
}

Once configured, just tell the AI:

"Generate a video from this script: /path/to/script.txt"

The AI will call the generate_video tool automatically.

---

📖 Tools

generate_video

Generate a complete video from a text script.

Parameters:

Param	Type	Default	Description
script_path	string	required	Path to script file
output_dir	string	out	Output directory
voice	string	male-qn-qingse	TTS voice ID
speed	float	1.05	Speech speed (0.5-2.0)
resolution	string	1920x1080	Output resolution
video_duration	int	10	Pexels clip duration per chapter (sec)

Returns:

{
  "success": true,
  "final_video": "out/final_video.mp4",
  "chapters": 3,
  "details": [
    {
      "chapter": 0,
      "title": "Chapter 1",
      "query": "search keywords",
      "video": "out/chapter_00/chapter.mp4",
      "tts": true
    }
  ]
}

list_voices

List available TTS voice IDs.

list_styles

List available video styles (planned).

---

📝 Script Format

Plain text (.txt) — Split with ---

Artificial intelligence is changing our lives. From smartphones to self-driving cars, AI is everywhere.

---

In healthcare, AI helps doctors diagnose diseases more accurately.

---

In the future, AI will continue to drive social progress.

Markdown (.md) — Split with ##

## The Rise of AI
Artificial intelligence is changing our lives...

## Healthcare Revolution
In healthcare, AI helps doctors...

## Future Outlook
In the future, AI will continue...

---

🎙️ Available Voices

ID	Name	Gender
male-qn-qingse	Youth	Male
female-shaonv	Girl	Female
male-qn-jingying	Elite Male	Male
female-yujie	Elegant Lady	Female
presenter male	Male Host	Male
presenter female	Female Host	Female

---

📂 Output Structure

out/
├── final_video.mp4              # ← Final complete video
├── concat.txt                   # ffmpeg merge list
├── chapter_00/
│   ├── source.mp4               # Pexels raw footage
│   ├── audio.mp3                # TTS narration audio
│   ├── audio.srt                # Subtitle file
│   └── chapter.mp4              # Composed chapter video
├── chapter_01/
│   └── ...
└── chapter_02/
    └── ...

---

🏗️ Workflow

                    ┌─────────────┐
                    │ Text Script │
                    │ .txt / .md  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │Parse Chapters│
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌──▼────┐ ┌─────▼─────┐
       │ Pexels Search│ │  TTS  │ │ Subtitles │
       │ Stock Videos │ │ Voice │ │   SRT     │
       └──────┬──────┘ └──┬────┘ └─────┬─────┘
              │           │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │ffmpeg Compose│
                    │Video+Audio+Sub│
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │ final.mp4   │
                    └─────────────┘

---

🔧 Requirements

• Python 3.8+
• ffmpeg (system install)
• requests
• fastmcp

---

💡 Why MCP?

MCP (Model Context Protocol) lets AI assistants call external tools directly. With this MCP Server installed:

• ✅ Claude Desktop can generate videos
• ✅ OpenClaw can generate videos
• ✅ Cursor can generate videos
• ✅ Any MCP-enabled AI assistant works

No coding needed. No command line. Just tell the AI.

---

📄 License

MIT

---

🤝 Contributing

PRs welcome! Especially:

• More TTS engines (Edge TTS, Azure TTS)
• More video sources (Pixabay, Coverr)
• AI image generation (DALL-E, Stable Diffusion)
• Custom subtitle styles
• Background music mixing

---

⭐ Star this repo

If you find this useful, give it a ⭐ to help others discover it!