Video Agent MCP Server

Un servidor MCP para la creación de videos impulsada por IA utilizando la API de FAL AI.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Video Agent

Un servidor integral de Protocolo de Contexto de Modelo (MCP) para la creación de video impulsada por IA. Este servidor proporciona herramientas, recursos y avisos para guiar a los agentes de IA a través de flujos de trabajo completos de producción de video.

Características

  • Interfaz unificada: Un único servidor MCP con todas las capacidades de creación de video
  • Integración multiservicio: Compatibilidad con servicios de FAL AI para generación de imágenes, video, audio y voz
  • Flujos de trabajo inteligentes: Avisos guiados que se adaptan al contexto de tu proyecto
  • Optimización de plataformas: Configuraciones predefinidas para YouTube, TikTok, Instagram y más
  • Seguimiento de costos: Estimación y seguimiento de costos en tiempo real para todas las operaciones
  • Integración con YouTube: Carga directa a YouTube con autenticación OAuth2
  • Arquitectura modular: Separación clara de herramientas, recursos y avisos

Inicio rápido

Requisitos previos

  • Python 3.11+
  • FFmpeg instalado en tu sistema
  • Clave de API de FAL AI
  • uv (administrador de paquetes de Python)

Instalación con uv

  1. Clona el repositorio:
git clone <repository-url>
cd video-gen-mcp-monolithic
  1. Instala uv (si aún no está instalado):
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. Configura el proyecto con uv:
# uv will automatically:
# - Detect Python 3.11 from .python-version
# - Create a virtual environment
# - Install all dependencies from pyproject.toml
uv sync

# Or if you want to install from requirements.txt:
uv pip install -r requirements.txt
  1. Configura las variables de entorno:
# Create a .env file in the project root
cat > .env << EOF
FALAI_API_KEY=your-fal-api-key
# Optional: For YouTube search features
GOOGLE_API_KEY=your-google-api-key
EOF

Ejecutar el servidor

# Run directly with uv (recommended)
uv run python main.py

# Or activate venv and run
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python main.py

Configurar Claude Desktop

Agrega lo siguiente a tu configuración de Claude Desktop:

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "video-agent": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/video-gen-mcp-monolithic",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "FALAI_API_KEY": "your-fal-api-key"
      }
    }
  }
}

Importante: Reemplaza /absolute/path/to/video-gen-mcp-monolithic con la ruta real a tu directorio de proyecto.

Alternativa: Usar el script de pyproject.toml

Dado que hemos definido un punto de entrada de script en pyproject.toml, también puedes ejecutar:

# Install the package in development mode
uv pip install -e .

# Run using the script entry point
uv run video-agent-mcp

Ejemplo de uso

Una vez configurado en Claude Desktop, puedes comenzar a crear videos:

User: Create a 30-second TikTok video about climate change

Claude: I'll help you create a TikTok video about climate change. Let me start by 
creating a project and planning the scenes...

[Claude uses the video_creation_wizard prompt and various tools to create the video]

Herramientas disponibles

Gestión de proyectos

  • create_project - Inicializa un nuevo proyecto de video con valores predeterminados inteligentes según la plataforma
  • add_scene - Agrega escenas a tu línea de tiempo con descripción y duración
  • list_projects - Ver todos los proyectos con su estado actual

Generación de contenido

  • generate_image_from_text - Crea imágenes a partir de avisos de texto con modificadores de estilo
  • generate_image_from_image - Transforma imágenes existentes con edición impulsada por IA
  • generate_video_from_image - Anima imágenes estáticas con movimiento generado por IA (compatible con modelos Kling 2.1 y Hailuo 02)
  • generate_music - Crea música de fondo a partir de descripciones de texto
  • generate_speech - Genera locuciones con múltiples opciones de voz

Herramientas de generación

Llama a las herramientas de generación secuencialmente para un seguimiento claro del progreso y una depuración más fácil.

Ensamblaje de video

  • download_assets - Descarga recursos generados desde FAL u otras fuentes
  • add_audio_track - Agrega pistas de audio al video con control de volumen
  • assemble_video - Combina escenas en el video final con ajustes preestablecidos de calidad

Utilidades

  • analyze_script - Analiza guiones para obtener información sobre producción de video
  • suggest_scenes - Genera sugerencias de escenas basadas en el guion del proyecto
  • upload_image_file - Sube archivos de imagen locales a FAL para usarlos en herramientas de generación
  • get_server_info - Obtén información sobre el servidor de Video Agent

Recursos

El servidor proporciona recursos dinámicos para la conciencia del contexto:

  • project://current - Detalles del proyecto actual
  • project://{id}/timeline - Línea de tiempo de escenas
  • project://{id}/costs - Desglose de costos
  • platform://{name}/specs - Especificaciones de la plataforma

Avisos

Los avisos interactivos guían flujos de trabajo complejos:

  • video_creation_wizard - Flujo de trabajo completo de creación de video con optimización de plataforma
  • script_to_scenes - Convierte guiones en planes de escenas con recomendaciones de tiempo
  • list_video_agent_capabilities - Guía completa de todas las capacidades del servidor
  • cinematic_photography_guide - Técnicas profesionales de cinematografía para visuales de IA

Configuración

Variables de entorno:

  • FALAI_API_KEY - Tu clave de API de FAL AI (requerida)
  • VIDEO_AGENT_STORAGE - Directorio de almacenamiento (predeterminado: ./storage)
  • DEFAULT_IMAGE_MODEL - Modelo de imagen predeterminado (predeterminado: imagen4)
  • DEFAULT_VIDEO_MODEL - Modelo de video predeterminado (predeterminado: kling_2.1, opciones: hailuo_02)

Estructura del proyecto

video-agent-mcp/
├── src/mcp_server/
│   ├── config/      # Configuration and settings
│   ├── models/      # Data models
│   ├── tools/       # Tool implementations
│   ├── resources/   # Resource handlers
│   ├── prompts/     # Prompt templates
│   └── services/    # External service integrations
├── templates/       # Video templates
└── tests/          # Test suite

Desarrollo

Configuración del entorno de desarrollo

# Clone and enter the project
git clone <repository-url>
cd video-gen-mcp-monolithic

# Install with development dependencies
uv sync --dev

# Or install dev dependencies separately
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

Agregar nuevas capacidades

  1. Nueva herramienta: Crea un archivo en src/mcp_server/tools/ y regístralo en server.py
  2. Nuevo recurso: Crea un controlador en resources/ y regístralo con el decorador
  3. Nuevo aviso: Agrégalo a prompts/ para flujos de trabajo guiados

Solución de problemas de uv

"No se encontró un intérprete de Python"

# uv will use the Python version from .python-version (3.11)
# If you need a specific Python version:
uv python install 3.11
uv venv --python 3.11

"Permiso denegado" en macOS/Linux

# Ensure uv is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Errores de "Módulo no encontrado"

# Ensure you're using uv run or have activated the venv
uv run python main.py
# OR
source .venv/bin/activate
python main.py

Claude Desktop no puede encontrar el servidor

  1. Usa rutas absolutas en la configuración
  2. Asegúrate de que FAL_API_KEY esté configurada en la sección de entorno
  3. Revisa los registros de Claude Desktop para ver errores
  4. Prueba el servidor de forma independiente primero: uv run python main.py

Integración con YouTube

Para la funcionalidad de carga a YouTube, consulta YOUTUBE_SETUP.md para obtener instrucciones detalladas de configuración de OAuth2.

Variables de entorno

Crea un archivo .env en la raíz del proyecto:

# Required
FALAI_API_KEY=your-fal-api-key

# Optional
VIDEO_AGENT_STORAGE=/path/to/storage  # Default: ./storage
DEFAULT_IMAGE_MODEL=imagen4           # Options: imagen4, flux_pro, flux_kontext
DEFAULT_VIDEO_MODEL=kling_2.1         # Options: kling_2.1, hailuo_02
GOOGLE_API_KEY=your-google-api-key    # For YouTube search features

Licencia

[Información de licencia]

Contribuciones

[Pautas de contribución]