This monorepo contains an MCP server for agentic video editing. It also powers a front-end human user editor. It’s built and maintained by HYE Partners.
You’ll need Node.js, npm (or pnpm/yarn), and Python 3.12+ (with pip).
These instructions assume a Unix-like OS (Mac/Linux), but should be adaptable for Windows.
Docker instructions below.
- Start the Python backend first (main.py)
- Then start the Node backend (npm run dev in ffmpeg-frontend)
- Then run the Python agent (ollamarun.py) for natural language jobs
- From your root coding project directory
- git clone https://github.com/hyepartners-gmail/vibevideo-mcp.git
- cd vibevideo-mcp
- cd ffmpeg-backend
- python3 -m venv .venv
- source .venv/bin/activate
- pip install -r requirements.txt
- pip install ffmpeg
- cd ffmpeg-frontend
- npm install
The project includes three main servers:
- URL: http://localhost:8080/
- Dev: Runs on Vite
- For: User front-end that gives you access to all of the video editing tools
- Run: (This launches both the React front-end and Node back-end in dev mode)
- npm run dev
- URL: http://localhost:8300/
- Dev: MCP Server, handles API requests from Python agents
- URL: http://127.0.0.1:8200
- For: Flask App handles all ffmpeg-powered media processing jobs
- Run:
- python main.py
- A simple Ollama agent running locally, for making one request at a time, media edits in natural language
- Run:
- python ollamarun.py
Suggested Models (must have function calling/tools):
- command-r7b:latest
- devstral:latest
- qwen3:latest
- phi4-mini:latest
- mistral-nemo:latest
- llama3.1:8b
- llama3.3:latest
- qwen2.5-coder:latest
- firefunction-v2:latest
- llama4:scout
If you want everything to "just work" via Docker:
Build and run both back-end servers with Docker Compose (from repo root):
docker-compose up --build
The following ports will be available:
Frontend (Vite): http://localhost:8080/ Node API server: http://localhost:8300/ Python FFmpeg backend: http://localhost:8200/
You can still use npm run dev/python main.py for local dev if you prefer. Note: The Docker setup mounts local source code, so edits will live-reload in most setups.
June 3rd 2025
- Better Timeline editing, Get Render working
- Dashboard Metrics / Run counts
- Connector to CrewAI
- MCP for some of the non-ffmpeg filters
- Free for any use: personal, research, or commercial.
- If you use this or build on top of it, a shout-out to HYE Partners is appreciated!
- If you fix bugs please submit PRs so everyone can benefit
Open use. Attribution requested, not required.
For issues, improvements, or collaboration, visit www.hyepartners.com.
-
These files are present in the repo under ffmpeg-backend/ and ffmpeg-frontend/.
-
If you don’t see them, make sure you’ve done a fresh git pull or git clone from the latest branch.
-
If issues persist, check your local .gitignore or .git/info/exclude for accidental blocks.
-
If pip install -r requirements.txt fails with missing modules (like Flask), open requirements.txt and manually add any missing packages.
-
Run pip install -r requirements.txt again.
-
If you get SyntaxError: Unexpected identifier 'assert', you need "type": "module" in your package.json, and Node.js >= 17.5+.
-
For maximum compatibility, use require() instead of import for JSON in server files, or convert the file to CommonJS if needed.
-
Python Backend (main.py) — must be running before the Node.js server.
-
Node.js Frontend/Backend (npm run dev) — launches both client and API server.
-
Python Agent (ollamarun.py) — optional, for natural language commands.
-
Docker Compose — launches all together.