ffmpeg-mcp

Um pacote Python para processamento de mídia usando FFmpeg e FastMCP.

GitHub
11
Experimente este MCPPatrocinado

Documentação

ffmpeg-mcp

ffmpeg-mcp 🎬⚡

Edite vídeo e áudio apenas conversando com seu assistente de IA.

ffmpeg-mcp é um servidor Model Context Protocol que coloca todo o poder do FFmpeg atrás de um conjunto limpo de ferramentas que seu LLM pode chamar — cortar, recortar, redimensionar, sobrepor, concatenar com transições, extrair quadros/áudio, criar GIFs e muito mais. Sem flags de linha de comando para memorizar.

Python FastMCP FFmpeg PRs Welcome Stars

✨ Por que ffmpeg-mcp?

FFmpeg é incrivelmente poderoso e incrivelmente difícil de memorizar. ffmpeg-mcp entrega esse poder ao seu assistente de IA para que você possa dizer o que deseja em português simples:

"Pegue os primeiros 10 segundos de demo.mov, redimensione para 1080p, coloque meu logotipo no canto superior direito e transforme em um GIF."

…e o modelo orquestra as ferramentas certas para você. Cada ferramenta é uma função Python pequena e validada — fácil de ler, reutilizar e estender.

  • 🗣️ Edição de vídeo em linguagem natural — funciona em qualquer cliente MCP (Claude Desktop, Cursor, Cline, …)
  • 🧱 12 ferramentas focadas — blocos de construção combináveis em vez de uma caixa preta gigante
  • ✅ Validação de entrada integrada — os caminhos são verificados quanto à existência, vazio e validade antes de o FFmpeg ser executado
  • 🧩 Personalizável — adicione uma nova ferramenta escrevendo uma função e registrando-a

🛠️ Ferramentas Disponíveis

FerramentaO que fazParâmetros principais
get_video_metadataAnalisar um arquivo para streams, codecs, duração, etc.input_video_path
extract_framesSalvar quadros como imagens (uniformemente, por intervalo ou 1/seg)input_video_path, number_of_frames?, timestamp_offset?
extract_audioExtrair áudio para um arquivo .wavinput_video_path
scale_videoAumentar resolução para 1080p / 2k / 4k, preservando proporçãoinput_video_path, resolution="1080p"
crop_videoRecortar para uma regiãoinput_video_path, width, height, x_offset, y_offset, safe_crop
clip_videoCortar um sub-clipe por início + duraçãoinput_video_path, start_timestamp, duration
make_gifTransformar um segmento em um GIF otimizadoinput_video_path, start_timestamp, duration
overlay_imageCompor uma imagem (logotipo/marca d'água) com tempo e opacidadeinput_video_path, overlay_image_path, positioning, opacity, start_time, duration
overlays_videoSobrepor um vídeo (em loop) em outroinput_video_path, overlay_video_path, positioning, scale
trim_and_concat_operationCortar vários clipes e costurá-los juntosinputs: [{path, start_time?, end_time?}], width, height
get_normalized_clipsNormalizar clipes para uma resolução/fps/codec comum (em paralelo)input_video_clips, resolution, frame_rate, crf
concat_clips_with_transitionConcatenar clipes com uma transição xfadeinput_video_clips, transition_type="fade", transition_duration

? marca parâmetros opcionais. concat_clips_with_transition suporta muitas transições — fade, wipeleft, slideup, circlecrop, dissolve, pixelize, radial, e dezenas mais.

📦 Requisitos

  • Python 3.12+
  • FFmpeg instalado e no seu PATH (fornece ffmpeg + ffprobe)
  • uv gerenciador de pacotes

Verifique se o FFmpeg está disponível:

ffmpeg -version

🚀 Início Rápido

1. Clone e instale

git clone https://github.com/yubraaj11/ffmpeg-mcp.git
cd ffmpeg-mcp
uv sync --frozen

2. Conecte-o ao seu cliente MCP

Aponte seu cliente para o servidor usando os trechos abaixo. Substitua /path/to/ffmpeg-mcp pelo caminho absoluto para seu clone.

Claude Desktop / Cursor (claude_desktop_config.json ou .cursor/mcp.json) 
{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" }
    }
  }
}
Cline (VS Code) 
{
  "mcpServers": {
    "ffmpeg-mcp": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" },
      "transportType": "stdio"
    }
  }
}

3. Reinicie seu cliente e comece a editar

"Extraia 5 quadros uniformemente espaçados de intro.mp4."

"Faça um GIF de 3 segundos de clip.mov começando em 12s."

"Concatene a.mp4, b.mp4 e c.mp4 com uma transição wipeleft de 1 segundo entre eles."

Os arquivos processados são gravados em ffmpeg_mcp/processed_elements/.

🧰 Estrutura do Projeto

ffmpeg_mcp/
├── main.py              # MCP server entry point — registers all tools
├── services/            # one module per tool
├── configs/             # colored logging setup
└── exceptions/          # structured error messages
utils/                   # validation decorators & helpers

Cada ferramenta retorna o caminho do arquivo de saída ou um erro JSON estruturado (status, error_type, message, time), para que falhas sejam fáceis de ler e recuperar pelo modelo.

🤝 Contribuindo

Contribuições são muito bem-vindas! Adicionar uma ferramenta é aproximadamente:

  1. Escreva uma função em ffmpeg_mcp/services/your_tool.py.
  2. Exporte-a de ffmpeg_mcp/services/__init__.py.
  3. Registre-a em main.py com mcp.tool(name_or_fn=your_tool).

Por favor, execute o linter antes de abrir um PR:

uv run ruff check .

Encontrou um bug ou tem uma ideia? Abra uma issue — e se este projeto te salvar de mais um mergulho na página de manual do ffmpeg, considere deixar uma ⭐.

📚 Construído Com