Media Generator MCP

Un server MCP (Model Context Protocol) per generare immagini e video utilizzando AI all'avanguardia.

Funzionalita

• Generazione Immagini: Crea immagini da descrizioni testuali usando Nano Banana Pro (Gemini 3 Pro Image Preview) via OpenRouter
• Editing Immagini: Modifica immagini esistenti con istruzioni in linguaggio naturale
• Animazione Video: Trasforma immagini statiche in video con Kling 2.6 Pro via fal.ai
• Workflow Completo: Genera video direttamente da testo (text → image → video)

Modelli Utilizzati

Funzione	Provider	Modello
Generazione/Editing Immagini	OpenRouter	google/gemini-3-pro-image-preview (Nano Banana Pro)
Animazione Video	fal.ai	fal-ai/kling-video/v2.6/pro/image-to-video

Requisiti

• Python 3.10+
• Account OpenRouter con API key
• Account fal.ai con API key

Installazione

1. Clona o scarica il progetto

cd /path/to/media-generator-mcp

2. Crea ambiente virtuale (consigliato)

python -m venv venv
source venv/bin/activate  # Linux/macOS
# oppure
.\venv\Scripts\activate   # Windows

3. Installa dipendenze

pip install -r requirements.txt

4. Configura le API keys

cp .env.example .env
# Modifica .env con le tue chiavi API

Oppure esporta le variabili d'ambiente:

export OPENROUTER_API_KEY="sk-or-v1-..."
export FAL_KEY="..."

Configurazione Claude Desktop

Aggiungi al tuo claude_desktop_config.json:

{
  "mcpServers": {
    "media-generator": {
      "command": "python",
      "args": ["/path/to/media-generator-mcp/server.py"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "FAL_KEY": "..."
      }
    }
  }
}

Con uv (alternativa)

{
  "mcpServers": {
    "media-generator": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/media-generator-mcp",
        "run", "server.py"
      ],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "FAL_KEY": "..."
      }
    }
  }
}

Tools Disponibili

1. image_generate - Genera Immagine da Testo

Crea un'immagine da una descrizione testuale dettagliata.

Parametri:

• prompt (required): Descrizione dell'immagine
• aspect_ratio: 1:1, 16:9, 9:16, 4:3, 21:9 (default: 1:1)
• image_size: 1K, 2K, 4K (default: 2K)
• style_prompt: Istruzioni di stile aggiuntive

Esempio:

Genera un'immagine di una citta futuristica al tramonto con grattacieli di vetro e macchine volanti

2. image_edit - Modifica Immagine

Modifica un'immagine esistente seguendo istruzioni testuali.

Parametri:

• image_url o image_base64 (required): Immagine da modificare
• edit_instructions (required): Cosa modificare
• aspect_ratio, image_size: Come sopra

Esempio:

Modifica l'immagine cambiando il cielo in un tramonto drammatico con colori arancioni e viola

3. video_animate - Anima Immagine in Video

Trasforma un'immagine statica in un video animato.

Parametri:

• image_url (required): URL dell'immagine da animare
• prompt (required): Descrizione del movimento desiderato
• duration: 5 o 10 secondi (default: 5)
• generate_audio: Genera audio sincronizzato (default: true)
• negative_prompt: Cosa evitare

Esempio:

Anima questa immagine con un lento zoom della camera, nuvole che si muovono nel cielo

4. media_generate - Workflow Completo Text-to-Video

Genera un video completo partendo solo da testo.

Parametri:

• prompt (required): Descrizione della scena
• animation_prompt: Istruzioni specifiche per l'animazione
• duration: 5 o 10 secondi
• generate_audio: Genera audio
• aspect_ratio, image_size, style_prompt

Esempio:

Crea un video di un gatto seduto su un davanzale che guarda la pioggia fuori dalla finestra.
Il gatto gira lentamente la testa e sbatte le palpebre.

Costi Stimati

Operazione	Costo Approssimativo
Generazione immagine	~$0.15
Video 5s senza audio	~$0.35
Video 5s con audio	~$0.70
Video 10s senza audio	~$0.70
Video 10s con audio	~$1.40

Output

Immagini

Le immagini vengono restituite in formato base64 PNG. Puoi salvarle decodificando il base64:

import base64
with open("image.png", "wb") as f:
    f.write(base64.b64decode(image_base64))

Video

I video vengono restituiti come URL diretti al file MP4 (ospitati su fal.ai). Gli URL hanno una scadenza temporale.

Troubleshooting

Errore "OPENROUTER_API_KEY not found"

Assicurati di aver configurato la variabile d'ambiente o il file .env.

Errore "FAL_KEY not found"

Verifica la configurazione della chiave fal.ai.

Errore 401/403

Le API keys potrebbero essere invalide o non avere i permessi necessari.

Errore 402

Crediti insufficienti. Ricarica il tuo account OpenRouter o fal.ai.

Timeout durante generazione video

I video possono richiedere 30-120 secondi. Se il timeout persiste, prova:

• Ridurre la durata a 5 secondi
• Disabilitare l'audio
• Usare un'immagine piu semplice

Licenza

MIT License