VFX MCP

Um servidor de edição de vídeo potente que utiliza ffmpeg-python para processar arquivos de vídeo externos.

Documentação

vfx-mcp 🎬

Um poderoso servidor MCP (Model Context Protocol) para edição de vídeo, construído com FastMCP e ffmpeg-python. Este servidor permite que LLMs realizem operações de edição de vídeo através de uma interface padronizada, possibilitando fluxos de trabalho de manipulação e processamento de vídeo com IA.

Recursos

Operações Principais de Vídeo

Corte e Aparação: Extrair segmentos específicos de vídeos
Concatenação: Juntar vários vídeos
Conversão de Formato: Transcodificar entre diferentes formatos de vídeo
Resolução e Qualidade: Redimensionar, alterar bitrate, ajustar qualidade
Processamento de Áudio: Extrair, substituir ou mixar faixas de áudio
Efeitos e Filtros: Aplicar filtros e efeitos do ffmpeg
Análise: Obter metadados do vídeo, gerar miniaturas
Operações Avançadas: Alterações de velocidade, reprodução reversa, loops

Recursos do MCP

Ferramentas: Executar operações de edição de vídeo
Recursos: Acessar e gerenciar arquivos de vídeo
Contexto: Relatório de progresso para operações longas
Streaming: Suporte para fluxos de trabalho baseados em arquivos e streaming

Instalação

Via PyPI (Recomendado) 🎉

# Install directly from PyPI
pip install vfx-mcp

# Run the server
vfx-mcp

Usando uv (Desenvolvimento)

# Clone the repository
git clone https://github.com/conneroisu/vfx-mcp.git
cd vfx-mcp

# Install dependencies with uv
uv sync

# Run the server
uv run python main.py

Usando Nix

# Enter the development shell
nix develop

# Run the server
python main.py

Requisitos do Sistema

Python 3.13+
FFmpeg (instalado automaticamente com Nix, ou instale manualmente)
gerenciador de pacotes uv (para instalação sem Nix)

Início Rápido

Uso Básico

# Connect to the VFX MCP server
from fastmcp import Client

async with Client("python main.py") as client:
    # Trim a video
    result = await client.call_tool("trim_video", {
        "input_path": "input.mp4",
        "output_path": "trimmed.mp4",
        "start_time": 10.0,
        "duration": 30.0
    })
    
    # Get video information
    info = await client.call_tool("get_video_info", {
        "video_path": "input.mp4"
    })
    print(info)

Uso via CLI com Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "vfx": {
      "command": "vfx-mcp",
      "args": []
    }
  }
}

Ou se estiver usando a versão de desenvolvimento:

{
  "mcpServers": {
    "vfx": {
      "command": "uv",
      "args": ["run", "python", "/path/to/vfx-mcp/main.py"],
      "cwd": "/path/to/vfx-mcp"
    }
  }
}

Referência da API

Ferramentas de Processamento de Vídeo

`trim_video`

Extrai um segmento de um vídeo.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de vídeo de saída
start_time (float): Tempo de início em segundos
duration (float, opcional): Duração em segundos (se não especificado, corta até o final)

`concatenate_videos`

Junta vários vídeos.

Parâmetros:

input_paths (list[str]): Lista de caminhos de arquivos de vídeo para concatenar
output_path (str): Caminho para o arquivo de vídeo de saída
transition (str, opcional): Tipo de transição entre vídeos

`convert_format`

Converte vídeo para formato ou codec diferente.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de vídeo de saída
format (str, opcional): Formato de saída (mp4, avi, mov, webm, etc.)
codec (str, opcional): Codec de vídeo (h264, h265, vp9, etc.)
audio_codec (str, opcional): Codec de áudio (aac, mp3, opus, etc.)

`resize_video`

Altera a resolução do vídeo.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de vídeo de saída
width (int, opcional): Largura alvo (mantém a proporção se a altura não for especificada)
height (int, opcional): Altura alvo (mantém a proporção se a largura não for especificada)
scale (float, opcional): Fator de escala (ex.: 0.5 para metade do tamanho)

`extract_audio`

Extrai a faixa de áudio do vídeo.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de áudio de saída
format (str, opcional): Formato de áudio (mp3, wav, aac, etc.)

`add_audio`

Adiciona ou substitui a faixa de áudio no vídeo.

Parâmetros:

video_path (str): Caminho para o arquivo de vídeo de entrada
audio_path (str): Caminho para o arquivo de áudio
output_path (str): Caminho para o arquivo de vídeo de saída
replace (bool, opcional): Substituir áudio existente (padrão: true)

`apply_filter`

Aplica filtro ffmpeg ao vídeo.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de vídeo de saída
filter (str): String de filtro do FFmpeg (ex.: "blur=10", "hflip", "reverse")

`change_speed`

Ajusta a velocidade de reprodução do vídeo.

Parâmetros:

input_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de vídeo de saída
speed (float): Multiplicador de velocidade (ex.: 2.0 para velocidade dupla, 0.5 para metade da velocidade)

`generate_thumbnail`

Extrai um quadro como miniatura de imagem.

Parâmetros:

video_path (str): Caminho para o arquivo de vídeo de entrada
output_path (str): Caminho para o arquivo de imagem de saída
timestamp (float, opcional): Tempo em segundos (padrão: meio do vídeo)

`get_video_info`

Obtém metadados detalhados do vídeo.

Parâmetros:

video_path (str): Caminho para o arquivo de vídeo

Retorna:

Metadados do vídeo incluindo duração, resolução, codec, bitrate, fps, etc.

Endpoints de Recursos

`videos://list`

Lista os arquivos de vídeo disponíveis no espaço de trabalho.

`videos://{filename}/metadata`

Obtém metadados para um arquivo de vídeo específico.

`videos://workspace/info`

Obtém informações do espaço de trabalho e armazenamento disponível.

Exemplos

Criar uma Montagem de Vídeo

async with Client("python main.py") as client:
    # 1. Trim clips from source videos
    clips = []
    for i, (video, start, duration) in enumerate([
        ("vacation.mp4", 30, 5),
        ("birthday.mp4", 120, 8),
        ("concert.mp4", 45, 6)
    ]):
        clip_path = f"clip_{i}.mp4"
        await client.call_tool("trim_video", {
            "input_path": video,
            "output_path": clip_path,
            "start_time": start,
            "duration": duration
        })
        clips.append(clip_path)
    
    # 2. Concatenate clips
    await client.call_tool("concatenate_videos", {
        "input_paths": clips,
        "output_path": "montage.mp4",
        "transition": "fade"
    })
    
    # 3. Add background music
    await client.call_tool("add_audio", {
        "video_path": "montage.mp4",
        "audio_path": "background_music.mp3",
        "output_path": "final_montage.mp4"
    })

Processar Vídeo para Web

async with Client("python main.py") as client:
    # Convert to web-friendly format with optimized settings
    await client.call_tool("convert_format", {
        "input_path": "raw_video.mov",
        "output_path": "web_video.mp4",
        "format": "mp4",
        "codec": "h264",
        "audio_codec": "aac"
    })
    
    # Create multiple resolutions
    for width in [1920, 1280, 854]:
        await client.call_tool("resize_video", {
            "input_path": "web_video.mp4",
            "output_path": f"web_video_{width}.mp4",
            "width": width
        })
    
    # Generate thumbnail
    await client.call_tool("generate_thumbnail", {
        "video_path": "web_video.mp4",
        "output_path": "thumbnail.jpg"
    })

Arquitetura

Estrutura do Projeto

vfx-mcp/
├── README.md              # This file
├── flake.nix             # Nix development environment
├── pyproject.toml        # Python project configuration
├── uv.lock              # Locked dependencies
├── main.py              # MCP server entry point
├── src/
│   ├── __init__.py
│   ├── server.py        # FastMCP server configuration
│   ├── tools/           # Video editing tool implementations
│   │   ├── __init__.py
│   │   ├── basic.py     # Basic operations (trim, concat, etc.)
│   │   ├── transform.py # Transformations (resize, rotate, etc.)
│   │   ├── audio.py     # Audio processing tools
│   │   └── effects.py   # Filters and effects
│   ├── resources/       # MCP resource handlers
│   │   └── videos.py    # Video file management
│   └── utils/           # Utility functions
│       ├── ffmpeg.py    # FFmpeg wrapper utilities
│       └── progress.py  # Progress reporting helpers
└── examples/            # Example usage scripts
    ├── montage.py       # Create video montage
    ├── web_process.py   # Process for web
    └── batch_convert.py # Batch conversion

Componentes Principais

Servidor FastMCP: Servidor central que lida com a comunicação do protocolo MCP
Módulos de Ferramentas: Organizados por funcionalidade (básico, transformação, áudio, efeitos)
Integração FFmpeg: Usando ffmpeg-python para processamento robusto de vídeo
Relatório de Progresso: Atualizações de progresso em tempo real para operações longas
Tratamento de Erros: Tratamento abrangente de erros para operações ffmpeg

Desenvolvimento

Configurando o Ambiente de Desenvolvimento

Com Nix (Recomendado para ambiente consistente)

# Enter development shell with all dependencies
nix develop

# Run tests
pytest

# Run linting
ruff check .

# Format code
ruff format .

Com uv

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

Adicionando Novas Ferramentas

Crie uma nova função no módulo apropriado em src/tools/
Use o decorador @mcp.tool
Adicione dicas de tipo e docstring adequadas
Implemente o tratamento de erros

Exemplo:

@mcp.tool
async def rotate_video(
    input_path: str,
    output_path: str,
    angle: int,
    ctx: Context
) -> str:
    """Rotate video by specified angle (90, 180, 270 degrees)."""
    if angle not in [90, 180, 270]:
        raise ValueError("Angle must be 90, 180, or 270 degrees")
    
    await ctx.info(f"Rotating video by {angle} degrees...")
    
    # Implementation using ffmpeg-python
    stream = ffmpeg.input(input_path)
    stream = ffmpeg.filter(stream, 'rotate', angle=math.radians(angle))
    stream = ffmpeg.output(stream, output_path)
    
    await run_ffmpeg_with_progress(stream, ctx)
    return f"Video rotated and saved to {output_path}"

Testes

Execute a suíte de testes:

# All tests
pytest

# Specific test file
pytest tests/test_basic_tools.py

# With coverage
pytest --cov=src

Contribuindo

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-tool)
Faça suas alterações e adicione testes
Execute linting e testes
Faça commit das suas alterações (git commit -m 'Add amazing tool')
Envie para o branch (git push origin feature/amazing-tool)
Abra um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes

Agradecimentos

Construído com FastMCP - O framework MCP rápido e Pythonico
Alimentado por ffmpeg-python - Bindings Python para FFmpeg
Usa Model Context Protocol - Padrão para integrações com LLM