MCP Video Converter Server

Converta arquivos de vídeo entre vários formatos usando FFmpeg. Requer que o FFmpeg esteja instalado no sistema.

Documentação

MCP Video Converter Server

Um servidor MCP que fornece ferramentas para verificar a instalação do FFmpeg e converter arquivos de vídeo entre vários formatos.

Recursos

Verificar FFmpeg: Verifica se o FFmpeg está instalado e acessível.
Converter Vídeo: Converte arquivos de vídeo, áudio e imagem para vários formatos (ex.: MP4, WebM, MOV, MP3, PNG).
Informações de Formato: Obtenha uma lista de formatos de arquivo suportados para conversão.

Pré-requisitos

Python 3.10+
FFmpeg instalado e disponível no PATH do seu sistema
[Opcional] uv para gerenciamento de ambiente

Configuração

Clone este repositório:

git clone https://github.com/adamanz/mcp-video-converter.git
cd mcp-video-converter

Crie e ative um ambiente virtual:

# Using venv (standard library)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or using uv (recommended if available)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Instale as dependências:

# Using pip
pip install -e .
pip install fastmcp

# Or using uv
uv pip install -e .
uv pip install fastmcp

Verifique sua instalação:

# Run the installation check script
python check_installation.py

Executando o Servidor Diretamente

Você pode executar o servidor diretamente:

# Activate the virtual environment if not already activated
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server
python -m mcp_video_converter.server

Integração com o Claude Desktop

Para adicionar este servidor MCP ao Claude Desktop:

Localize ou crie o arquivo de configuração do Claude Desktop:

# macOS
mkdir -p ~/Library/Application\ Support/Claude/
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
mkdir -p %APPDATA%\Claude\
notepad %APPDATA%\Claude\claude_desktop_config.json

Adicione a configuração do servidor MCP:

{
  "mcpServers": {
    "video-convert": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "cd /absolute/path/to/mcp-video-converter && source .venv/bin/activate && python -m mcp_video_converter.server"
      ]
    }
  }
}

Alternativa para Windows:

{
  "mcpServers": {
    "video-convert": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "cd /d C:\\absolute\\path\\to\\mcp-video-converter && .venv\\Scripts\\activate && python -m mcp_video_converter.server"
      ]
    }
  }
}

Substitua /absolute/path/to/mcp-video-converter pelo caminho absoluto do seu repositório.

Reinicie o Claude Desktop
- O servidor aparecerá como "video-convert" no menu de ferramentas MCP
Notas importantes:
- Sempre use caminhos absolutos na sua configuração
- Certifique-se de que o FFmpeg esteja instalado e no seu PATH
- Se encontrar problemas, verifique os logs do Claude Desktop:
```
# macOS
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\logs\mcp*.log
```

Integração com o Cursor

Para adicionar este servidor MCP ao Cursor:

Localize ou crie o arquivo de configuração do Cursor:

# macOS
mkdir -p ~/.cursor/
nano ~/.cursor/config.json

# Windows
mkdir -p %USERPROFILE%\.cursor\
notepad %USERPROFILE%\.cursor\config.json

Adicione a configuração do servidor MCP:

{
  "ai": {
    "mcpServers": {
      "video-convert": {
        "command": "/bin/bash",
        "args": [
          "-c",
          "cd /absolute/path/to/mcp-video-converter && source .venv/bin/activate && python -m mcp_video_converter.server"
        ]
      }
    }
  }
}

Alternativa para Windows:

{
  "ai": {
    "mcpServers": {
      "video-convert": {
        "command": "cmd.exe",
        "args": [
          "/c",
          "cd /d C:\\absolute\\path\\to\\mcp-video-converter && .venv\\Scripts\\activate && python -m mcp_video_converter.server"
        ]
      }
    }
  }
}

Substitua /absolute/path/to/mcp-video-converter pelo caminho absoluto do seu repositório.

Reinicie o Cursor
- O servidor estará disponível para o Claude no Cursor
Notas importantes:
- Sempre use caminhos absolutos na sua configuração
- Certifique-se de que o FFmpeg esteja instalado e no seu PATH
- Os logs podem ser acessados pelas ferramentas de desenvolvedor do Cursor

Implantação com o Smithery

O Smithery é uma plataforma que simplifica a implantação e o gerenciamento de servidores MCP. Este projeto está totalmente configurado para implantação no Smithery, com os arquivos e configurações necessários.

Arquivos de Configuração Necessários

Este projeto inclui todos os arquivos de configuração necessários para a implantação no Smithery:

smithery.yaml: Define como iniciar seu servidor e suas opções de configuração
Dockerfile: Define como construir a imagem do contêiner do seu servidor

Configuração YAML do Smithery

O arquivo smithery.yaml fornece ao Smithery instruções sobre como executar seu servidor:

startCommand:
  type: stdio
  configSchema:
    type: object
    properties:
      ffmpegPath:
        type: string
        title: "FFmpeg Path"
        description: "Optional path to FFmpeg executable (uses system PATH by default)"
      outputDirectory:
        type: string
        title: "Output Directory"
        description: "Optional custom directory for output files"
      quality:
        type: string
        enum: ["low", "medium", "high"]
        default: "medium"
        title: "Default Quality"
  name: "MCP Video Converter"
  description: "Convert video files between formats and check FFmpeg installation"
  commandFunction: |
    (config) => {
      // Function that returns command details based on configuration options
    }

build:
  dockerfile: Dockerfile
  dockerBuildPath: .
  env:
    OUTPUT_DIRECTORY: "/data/converted"
  buildOptions:
    buildArgs:
      PYTHON_VERSION: "3.10"
      INSTALL_DEV: "false"
    labels:
      org.opencontainers.image.source: "https://github.com/adamanz/mcp-video-converter"
      org.opencontainers.image.description: "MCP Server for video conversion using FFmpeg"
      org.opencontainers.image.licenses: "MIT"

Componentes principais:

type: stdio: Define que nosso servidor usa o transporte padrão de E/S
configSchema: Define as opções de configuração que os usuários podem definir (caminho do FFmpeg, diretório de saída, qualidade)
commandFunction: Função JavaScript que retorna como iniciar o servidor com base na configuração
build: Configuração específica do contêiner para implantação com Docker

Implantando no Smithery

Instale a CLI do Smithery, se ainda não tiver:

# Install the Smithery command-line tool
npm install -g @smithery/cli

Faça login no Smithery:
```
smithery login
```

Implante diretamente do repositório:

# Navigate to the repository directory
cd /path/to/adamanz/mcp-video-converter

# Deploy to Smithery
smithery deploy

Alternativamente, implante com opções de build explícitas:

# Deploy with container build
smithery deploy --build

# Deploy with custom build arguments
smithery deploy --build --build-arg PYTHON_VERSION=3.11

Configure e inicie o servidor no Smithery:

# Configure the server (interactive)
smithery configure mcp-video-converter

# Start the server
smithery start mcp-video-converter

Suporte a Docker

Este projeto inclui um Dockerfile de múltiplos estágios para implantação eficiente em contêiner. O contêiner:

Usa um processo de build de múltiplos estágios para reduzir o tamanho final da imagem
Instala o FFmpeg e todas as dependências necessárias
Cria um ponto de montagem de volume dedicado para arquivos convertidos
Inclui um healthcheck para melhor monitoramento do contêiner

Você pode construir e executar o contêiner Docker manualmente:

# Build the container
docker build -t mcp-video-converter .

# Run the container
docker run -it --rm \
  -v $(pwd)/converted:/data/converted \
  -e FFMPEG_PATH=/usr/bin/ffmpeg \
  -e DEFAULT_QUALITY=high \
  mcp-video-converter

Considerações sobre Hospedagem Serverless

Ao implantar no ambiente serverless do Smithery, esteja ciente do seguinte:

Tempo limite de conexão: As conexões com seu servidor expirarão após 2 minutos de inatividade
Armazenamento efêmero: Projete seu servidor pensando em armazenamento efêmero
Design sem estado: O servidor não deve depender de armazenamento local persistente
Arquivos de saída: As saídas da conversão de vídeo devem ser retornadas adequadamente como parte da resposta da ferramenta para garantir que os clientes possam acessá-las

Gerenciamento do Smithery

Comandos úteis do Smithery para gerenciar sua implantação:

# View server logs
smithery logs mcp-video-converter

# Update to latest version
smithery update mcp-video-converter

# Stop the server
smithery stop mcp-video-converter

# Remove the server
smithery remove mcp-video-converter

Integração com Aplicativos Smithery

Os usuários podem acessar seu servidor pelo aplicativo Smithery:

Abra o aplicativo Smithery
Navegue até a aba "Servers"
Selecione "mcp-video-converter"
Configure as configurações se solicitado (caminho do FFmpeg, diretório de saída, qualidade)
Conecte-se ao servidor
Use o servidor com clientes MCP compatíveis

Testes Antes da Implantação

Antes de implantar no Smithery, é recomendado testar seu servidor localmente:

# Test with MCP Inspector (if available)
mcp-inspector -s /path/to/mcp-video-converter/smithery.yaml

# Or test by running the server directly
cd /path/to/mcp-video-converter
python -m mcp_video_converter.server

Solução de Problemas Comuns

Servidor Não Encontrado

Se o servidor MCP não estiver sendo detectado:

Verifique se os caminhos no seu arquivo de configuração são absolutos e corretos
Verifique se o FFmpeg está instalado e no seu PATH
Certifique-se de que o ambiente virtual esteja ativado no seu comando
Verifique os logs para mensagens de erro específicas

Módulo Python Não Encontrado

Se você vir erros sobre módulos ausentes:

Certifique-se de ter instalado todas as dependências com pip install -e . e pip install fastmcp
Verifique se o ambiente virtual está sendo ativado corretamente
Tente reinstalar o pacote: pip install -e .

FFmpeg Não Encontrado

Se o FFmpeg não puder ser encontrado:

Verifique se o FFmpeg está instalado: which ffmpeg ou where ffmpeg no Windows
Adicione o diretório do FFmpeg ao seu PATH
Na configuração, você pode especificar o caminho completo para o FFmpeg:
```
"env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin:/path/to/ffmpeg/bin"
}
```

Exemplo de Uso (com Claude)

Após a integração, você pode pedir ao Claude para realizar tarefas como:

"Verifique se o FFmpeg está instalado no meu sistema"
"Converta este arquivo de vídeo: /path/to/video.webm para o formato MP4 com alta qualidade"
"Quais formatos de vídeo posso converter?"

O Claude usará as ferramentas apropriadas do servidor MCP para realizar essas tarefas.

Avançado: Usando com o cliente fastmcp

Para uso programático, você pode usar o cliente fastmcp:

# Check FFmpeg installation
fastmcp client call <SERVER_URL_OR_FILE_PATH> check_ffmpeg_installed '{}'

# Get supported formats
fastmcp client call <SERVER_URL_OR_FILE_PATH> get_supported_formats '{}'

# Convert a video
fastmcp client call <SERVER_URL_OR_FILE_PATH> convert_video '{
  "input_file_path": "/path/to/your/video.webm", 
  "output_format": "mp4", 
  "quality": "high"
}'

Substitua /path/to/your/video.webm por um caminho real de arquivo de vídeo.

Formatos Suportados

Vídeo: MP4, WebM, MOV, AVI, MKV, FLV, GIF
Áudio: MP3, WAV, OGG, AAC, M4A
Imagem: WebP, JPG, PNG, BMP, TIFF

Executando Testes

# Using pip
pip install pytest
pytest

# Using uv
uv pip install pytest
uv run pytest

Licença

Este projeto é open source e está disponível sob a Licença MIT.

Contribuição

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para detalhes sobre como contribuir com este projeto.