# 🎬 AI Video MCP Server

> **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](https://smithery.ai/badge/ai-video-mcp)](https://smithery.ai/server/ai-video-mcp)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](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

```bash
pip install ai-video-mcp
```

Or from source:

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

### 2. Set API Keys

```bash
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](https://platform.minimaxi.com) | TTS voice synthesis |
| PEXELS_API_KEY | [pexels.com/api](https://www.pexels.com/api/) | Stock video search |

### 3. Use

#### Command Line

```bash
ai-video-mcp
```

#### MCP Config (Claude Desktop / OpenClaw / Cursor)

```json
{
  "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:**

```json
{
  "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 `---`

```text
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 `## `

```markdown
## 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!