# video-mcp

An [MCP](https://modelcontextprotocol.io) server that gives Claude the ability to **generate videos from text** using the [Replicate](https://replicate.com) API.

Just ask Claude: *"Make a 6-second video of a red fox running through a snowy forest"* — and get a video link (or a file on your disk) a couple of minutes later.

<!-- Add a demo GIF here: ![demo](demo.gif) -->

## How it works

```
You ──► Claude Desktop ──► video-mcp (this server) ──► Replicate API ──► video model
                    ◄──────────── video URL / .mp4 file ◄──────────────
```

Claude decides when to call the tools, writes a good prompt for the video model, waits for the result and shows you the link.

## Tools

| Tool | What it does |
|---|---|
| `generate_video` | Starts video generation from a text prompt (optionally with a first-frame image). Waits up to ~50 s, then returns either the video URL or a generation ID. |
| `check_video` | Checks the status of a generation by ID and returns the URL when it's ready. |
| `download_video` | Downloads a finished video to `~/Videos/video-mcp`. |

Default model: [`minimax/video-01`](https://replicate.com/minimax/video-01) (6 s, 720p). Any Replicate video model that accepts a `prompt` input can be used via the `model` argument or the `VIDEO_MODEL` env variable.

## Setup

### 1. Requirements

- [Claude Desktop](https://claude.ai/download)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python package manager — it installs Python and dependencies automatically)
- A Replicate API token: <https://replicate.com/account/api-tokens> (paid, billed per generation)

### 2. Get the code

```bash
git clone https://github.com/kuuuuorti/video-mcp.git
```

### 3. Connect to Claude Desktop

Open **Claude Desktop → Settings → Developer → Edit Config** and add:

```json
{
  "mcpServers": {
    "video": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/video-mcp", "run", "server.py"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}
```

Windows path example: `"C:\\Users\\you\\video-mcp"`.

Restart Claude Desktop completely. The `video` server should appear in the tools menu.

### Optional environment variables

| Variable | Default | Description |
|---|---|---|
| `VIDEO_MODEL` | `minimax/video-01` | Replicate model, `owner/name` |
| `VIDEO_OUTPUT_DIR` | `~/Videos/video-mcp` | Where `download_video` saves files |

## Example prompts

- "Generate a video: a cozy coffee shop on a rainy evening, camera slowly moving towards the window"
- "Make a video from this image as the first frame: https://… , the character turns and smiles"
- "Check my video generation status and download it when ready"

## Development

Test the server with the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector uv --directory . run server.py
```

## Tech stack

Python · [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) · httpx (async) · Replicate HTTP API

## License

MIT