MCP Video Converter Server

Convierte archivos de video entre varios formatos usando FFmpeg. Requiere que FFmpeg esté instalado en el sistema.

GitHubPrueba este MCPPatrocinado

Documentación

MCP Video Converter Server

Un servidor MCP que proporciona herramientas para verificar la instalación de FFmpeg y convertir archivos de video entre varios formatos.

Características

  • Verificar FFmpeg: Comprueba si FFmpeg está instalado y accesible.
  • Convertir Video: Convierte archivos de video, audio e imagen a varios formatos (por ejemplo, MP4, WebM, MOV, MP3, PNG).
  • Información de Formatos: Obtén una lista de formatos de archivo compatibles para la conversión.

Requisitos previos

  • Python 3.10+
  • FFmpeg instalado y disponible en el PATH de tu sistema
  • [Opcional] uv para la gestión del entorno

Configuración

  1. Clona este repositorio:

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

  2. Crea y activa un entorno 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

  3. Instala las dependencias:

    # Using pip
pip install -e .
pip install fastmcp

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

  4. Verifica tu instalación:

    # Run the installation check script
python check_installation.py

Ejecutar el Servidor Directamente

Puedes ejecutar el servidor directamente:

# 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

Integración con Claude Desktop

Para agregar este servidor MCP a Claude Desktop:

  1. Localiza o crea el archivo de configuración de 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

  2. Agrega la configuración del 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"
      ]
    }
  }
}

    Reemplaza /absolute/path/to/mcp-video-converter con la ruta absoluta a tu repositorio.

  3. Reinicia Claude Desktop

    • El servidor aparecerá como "video-convert" en el menú de herramientas MCP

  4. Notas importantes:

    • Usa siempre rutas absolutas en tu configuración
    • Asegúrate de que FFmpeg esté instalado y en tu PATH
    • Si encuentras problemas, revisa los registros de Claude Desktop: 
      # macOS
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

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

Integración con Cursor

Para agregar este servidor MCP a Cursor:

  1. Localiza o crea el archivo de configuración de Cursor:

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

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

  2. Agrega la configuración del 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"
        ]
      }
    }
  }
}

    Reemplaza /absolute/path/to/mcp-video-converter con la ruta absoluta a tu repositorio.

  3. Reinicia Cursor

    • El servidor estará disponible para Claude en Cursor

  4. Notas importantes:

    • Usa siempre rutas absolutas en tu configuración
    • Asegúrate de que FFmpeg esté instalado y en tu PATH
    • Los registros se pueden acceder a través de las herramientas de desarrollador de Cursor

Despliegue con Smithery

Smithery es una plataforma que simplifica el despliegue y la gestión de servidores MCP. Este proyecto está completamente configurado para el despliegue con Smithery, con los archivos y configuraciones requeridos.

Archivos de Configuración Requeridos

Este proyecto incluye todos los archivos de configuración requeridos para el despliegue con Smithery:

  1. smithery.yaml: Define cómo iniciar tu servidor y sus opciones de configuración
  2. Dockerfile: Define cómo construir la imagen de contenedor de tu servidor

Configuración YAML de Smithery

El archivo smithery.yaml proporciona a Smithery instrucciones sobre cómo ejecutar tu 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 clave:

  • type: stdio: Define que nuestro servidor utiliza el transporte estándar de E/S
  • configSchema: Define las opciones de configuración que los usuarios pueden establecer (ruta de FFmpeg, directorio de salida, calidad)
  • commandFunction: Función de JavaScript que devuelve cómo iniciar el servidor según la configuración
  • build: Configuración específica del contenedor para el despliegue con Docker

Despliegue en Smithery

  1. Instala la CLI de Smithery si aún no lo has hecho:

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

  2. Inicia sesión en Smithery:

    smithery login

  3. Despliega directamente desde el repositorio:

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

# Deploy to Smithery
smithery deploy

    Alternativamente, despliega con opciones de compilación explícitas:

    # Deploy with container build
smithery deploy --build

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

  4. Configura e inicia el servidor en Smithery:

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

# Start the server
smithery start mcp-video-converter

Soporte de Docker

Este proyecto incluye un Dockerfile de múltiples etapas para un despliegue contenerizado eficiente. El contenedor:

  • Utiliza un proceso de compilación de múltiples etapas para reducir el tamaño final de la imagen
  • Instala FFmpeg y todas las dependencias requeridas
  • Crea un punto de montaje de volumen dedicado para los archivos convertidos
  • Incluye una verificación de salud para un mejor monitoreo del contenedor

Puedes compilar y ejecutar el contenedor 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

Consideraciones de Alojamiento Serverless

Al desplegar en el entorno serverless de Smithery, ten en cuenta lo siguiente:

  • Tiempo de Espera de Conexión: Las conexiones a tu servidor expirarán después de 2 minutos de inactividad
  • Almacenamiento Efímero: Diseña tu servidor teniendo en cuenta el almacenamiento efímero
  • Diseño Sin Estado: El servidor no debe depender de almacenamiento local persistente
  • Archivos de Salida: Las salidas de conversión de video deben devolverse correctamente como parte de la respuesta de la herramienta para garantizar que los clientes puedan acceder a ellas

Gestión de Smithery

Comandos útiles de Smithery para gestionar tu despliegue:

# 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

Integración con Aplicaciones de Smithery

Los usuarios pueden acceder a tu servidor a través de la aplicación de Smithery:

  1. Abre la aplicación de Smithery
  2. Navega a la pestaña "Servers"
  3. Selecciona "mcp-video-converter"
  4. Configura los ajustes si se te solicita (ruta de FFmpeg, directorio de salida, calidad)
  5. Conéctate al servidor
  6. Usa el servidor con clientes MCP compatibles

Pruebas Antes del Despliegue

Antes de desplegar en Smithery, se recomienda probar tu 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

Solución de Problemas Comunes

Servidor No Encontrado

Si el servidor MCP no se está detectando:

  1. Verifica que las rutas en tu archivo de configuración sean absolutas y correctas
  2. Comprueba que FFmpeg esté instalado y en tu PATH
  3. Asegúrate de que el entorno virtual esté activado en tu comando
  4. Revisa los registros para ver mensajes de error específicos

Módulo de Python No Encontrado

Si ves errores sobre módulos faltantes:

  1. Asegúrate de haber instalado todas las dependencias con pip install -e . y pip install fastmcp
  2. Verifica que el entorno virtual se esté activando correctamente
  3. Intenta reinstalar el paquete: pip install -e .

FFmpeg No Encontrado

Si no se puede encontrar FFmpeg:

  1. Verifica que FFmpeg esté instalado: which ffmpeg o where ffmpeg en Windows
  2. Agrega el directorio de FFmpeg a tu PATH
  3. En la configuración, puedes especificar la ruta completa a FFmpeg: 
    "env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin:/path/to/ffmpeg/bin"
}

Ejemplo de Uso (con Claude)

Una vez integrado, puedes pedirle a Claude que realice tareas como:

  1. "Comprueba si FFmpeg está instalado en mi sistema"
  2. "Convierte este archivo de video: /path/to/video.webm a formato MP4 con alta calidad"
  3. "¿A qué formatos de video puedo convertir?"

Claude utilizará las herramientas apropiadas del servidor MCP para realizar estas tareas.

Avanzado: Uso con el cliente fastmcp

Para uso programático, puedes usar el 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"
}'

Reemplaza /path/to/your/video.webm con una ruta real de archivo de video.

Formatos Compatibles

  • Video: MP4, WebM, MOV, AVI, MKV, FLV, GIF
  • Audio: MP3, WAV, OGG, AAC, M4A
  • Imagen: WebP, JPG, PNG, BMP, TIFF

Ejecutar Pruebas

# Using pip
pip install pytest
pytest

# Using uv
uv pip install pytest
uv run pytest

Licencia

Este proyecto es de código abierto y está disponible bajo la Licencia MIT.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para obtener detalles sobre cómo contribuir a este proyecto.