Video Agent MCP Server

Um servidor MCP para criação de vídeos com inteligência artificial usando a API FAL AI.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Agente de Vídeo

Um servidor abrangente de Protocolo de Contexto de Modelo (MCP) para criação de vídeos com IA. Este servidor fornece ferramentas, recursos e prompts para guiar agentes de IA em fluxos de trabalho completos de produção de vídeo.

Recursos

  • Interface Unificada: Servidor MCP único com todas as capacidades de criação de vídeo
  • Integração Multi-Serviço: Suporta serviços FAL AI para geração de imagem, vídeo, áudio e fala
  • Fluxos de Trabalho Inteligentes: Prompts guiados que se adaptam ao contexto do seu projeto
  • Otimização de Plataforma: Configurações pré-definidas para YouTube, TikTok, Instagram e mais
  • Rastreamento de Custos: Estimativa e rastreamento de custos em tempo real para todas as operações
  • Integração com YouTube: Upload direto para o YouTube com autenticação OAuth2
  • Arquitetura Modular: Separação clara de ferramentas, recursos e prompts

Início Rápido

Pré-requisitos

  • Python 3.11+
  • FFmpeg instalado no seu sistema
  • Chave de API FAL AI
  • uv (gerenciador de pacotes Python)

Instalação com uv

  1. Clone o repositório:
git clone <repository-url>
cd video-gen-mcp-monolithic
  1. Instale o uv (se ainda não estiver 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. Configure o projeto com 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. Configure as variáveis de ambiente:
# 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

Executando o 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

Configurando o Claude Desktop

Adicione o seguinte à configuração do seu Claude Desktop:

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json No 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: Substitua /absolute/path/to/video-gen-mcp-monolithic pelo caminho real do diretório do seu projeto.

Alternativa: Usando o script do pyproject.toml

Como definimos um ponto de entrada de script no pyproject.toml, você também pode executar:

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

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

Exemplo de Uso

Uma vez configurado no Claude Desktop, você pode começar a criar vídeos:

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]

Ferramentas Disponíveis

Gerenciamento de Projetos

  • create_project - Inicializa um novo projeto de vídeo com padrões inteligentes baseados na plataforma
  • add_scene - Adiciona cenas à sua linha do tempo com descrição e duração
  • list_projects - Visualiza todos os projetos com seu status atual

Geração de Conteúdo

  • generate_image_from_text - Cria imagens a partir de prompts de texto com modificadores de estilo
  • generate_image_from_image - Transforma imagens existentes com edição alimentada por IA
  • generate_video_from_image - Anima imagens estáticas com movimento gerado por IA (suporta modelos Kling 2.1 e Hailuo 02)
  • generate_music - Cria música de fundo a partir de descrições de texto
  • generate_speech - Gera narrações com múltiplas opções de voz

Ferramentas de Geração

Chame as ferramentas de geração sequencialmente para um rastreamento claro de progresso e depuração mais fácil.

Montagem de Vídeo

  • download_assets - Baixa ativos gerados do FAL ou outras fontes
  • add_audio_track - Adiciona faixas de áudio ao vídeo com controle de volume
  • assemble_video - Combina cenas no vídeo final com predefinições de qualidade

Utilitários

  • analyze_script - Analisa roteiros para insights de produção de vídeo
  • suggest_scenes - Gera sugestões de cenas com base no roteiro do projeto
  • upload_image_file - Envia arquivos de imagem locais para o FAL para uso nas ferramentas de geração
  • get_server_info - Obtém informações sobre o servidor Video Agent

Recursos

O servidor fornece recursos dinâmicos para consciência de contexto:

  • project://current - Detalhes do projeto atual
  • project://{id}/timeline - Linha do tempo de cenas
  • project://{id}/costs - Detalhamento de custos
  • platform://{name}/specs - Especificações da plataforma

Prompts

Prompts interativos guiam fluxos de trabalho complexos:

  • video_creation_wizard - Fluxo de trabalho completo de criação de vídeo com otimização de plataforma
  • script_to_scenes - Converte roteiros em planos de cenas com recomendações de tempo
  • list_video_agent_capabilities - Guia abrangente de todas as capacidades do servidor
  • cinematic_photography_guide - Técnicas profissionais de cinematografia para visuais de IA

Configuração

Variáveis de ambiente:

  • FALAI_API_KEY - Sua chave de API FAL AI (obrigatória)
  • VIDEO_AGENT_STORAGE - Diretório de armazenamento (padrão: ./storage)
  • DEFAULT_IMAGE_MODEL - Modelo de imagem padrão (padrão: imagen4)
  • DEFAULT_VIDEO_MODEL - Modelo de vídeo padrão (padrão: kling_2.1, opções: hailuo_02)

Estrutura do Projeto

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

Desenvolvimento

Configurando o Ambiente de Desenvolvimento

# 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 .

Adicionando Novas Capacidades

  1. Nova Ferramenta: Crie um arquivo em src/mcp_server/tools/ e registre em server.py
  2. Novo Recurso: Crie um manipulador em resources/ e registre com decorador
  3. Novo Prompt: Adicione a prompts/ para fluxos de trabalho guiados

Solução de Problemas com uv

"Nenhum interpretador Python encontrado"

# 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

"Permissão negada" no macOS/Linux

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

Erros de "Módulo não 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

O Claude Desktop não consegue encontrar o servidor

  1. Use caminhos absolutos na configuração
  2. Certifique-se de que FAL_API_KEY está definido na seção de ambiente
  3. Verifique os logs do Claude Desktop para erros
  4. Teste o servidor standalone primeiro: uv run python main.py

Integração com YouTube

Para funcionalidade de upload no YouTube, consulte YOUTUBE_SETUP.md para instruções detalhadas de configuração OAuth2.

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# 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

Licença

[Informações de licença]

Contribuição

[Diretrizes de contribuição]