FFmpeg视频处理服务器

🎬 FFmpeg MCP Server - Documentazione Completa

Server MCP (Model Context Protocol) per FFmpeg con 11 funzionalità essenziali di manipolazione video, audio e creazione contenuti multimediali.

📦 Funzionalità Disponibili

Totale: 11 Tools Essenziali

📋 Indice

• Installazione
• Configurazione
• Categorie Funzionalità
• Documentazione Tools
  • Informazioni e Analisi
  • Conversione e Compressione
  • Manipolazione Audio
  • Manipolazione Video
  • Filtri ed Effetti
  • Thumbnail e Frame
  • Creazione Video
  • GIF e Formati Web
  • Preset Social Media
• Esempi Pratici
• Troubleshooting

🚀 Installazione

Prerequisiti

1. Node.js (v18 o superiore)
2. FFmpeg installato e nel PATH di sistema
3. Claude Desktop installato

Verifica Prerequisiti

node --version
npm --version
ffmpeg -version

Setup Progetto

# Naviga nella cartella del progetto
cd C:\DEV\MCP\mcp-ffmpeg-server

# Installa dipendenze
npm install

⚙️ Configurazione

1. Configura Claude Desktop

Modifica il file di configurazione:

• Percorso: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ffmpeg": {
      "command": "node",
      "args": ["C:\\DEV\\MCP\\mcp-ffmpeg-server\\server.js"]
    }
  }
}

Nota: Aggiorna il percorso C:\\DEV\\MCP\\mcp-ffmpeg-server\\server.js con il percorso effettivo del tuo progetto.

2. Riavvia Claude Desktop

Chiudi completamente Claude Desktop e riaprilo per caricare il server.

3. Verifica Connessione

In Claude Desktop, controlla che il server sia attivo in Settings → Developer.

📦 Categorie Funzionalità

Totale: 40+ Tools

📖 Documentazione Tools

📊 Informazioni e Analisi

get_video_info

Ottiene informazioni dettagliate su un file video.

Parametri:

• video_path (string, required): Percorso del file video

Esempio:

Ottieni informazioni su D:\video.mp4

Output: JSON con codec, risoluzione, durata, bitrate, frame rate, ecc.

Note:

• Usa ffprobe per analizzare il file
• Ritorna formato JSON completo con tutti gli stream

compare_videos

Crea un video side-by-side per confrontare due video.

Parametri:

• video1_path (string, required): Percorso primo video
• video2_path (string, required): Percorso secondo video
• output_path (string, required): Percorso output
• layout (string, default: "horizontal"): Layout - "horizontal" o "vertical"

Esempio:

Confronta D:\original.mp4 e D:\edited.mp4 orizzontalmente, salva in D:\comparison.mp4

🔄 Conversione e Compressione

convert_video

Converte un video in un altro formato.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• format (string, required): Formato output (mp4, avi, mkv, webm, mov)

Esempio:

Converti D:\video.avi in MP4 e salva come D:\video.mp4

Note:

• FFmpeg rileva automaticamente il formato dall'estensione
• Mantiene codec originali quando possibile

compress_video

Comprime un video riducendone la dimensione.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• quality (string, default: "medium"): Qualità - "low", "medium", "high"

Esempio:

Comprimi D:\video.mp4 con qualità media e salva in D:\video_compressed.mp4

Note:

• low: CRF 28 (massima compressione, qualità ridotta)
• medium: CRF 23 (bilanciato, consigliato)
• high: CRF 18 (alta qualità, file più grande)
• Usa codec H.264 e AAC per compatibilità universale

extract_segment_by_size

Estrae un segmento video per raggiungere una dimensione file specifica.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• target_size_mb (number, required): Dimensione target in MB
• start_time (string, default: "00:00:00"): Tempo di inizio

Esempio:

Estrai un segmento di circa 50MB da D:\video.mp4 partendo dal minuto 2, salva in D:\segment.mp4

🎵 Manipolazione Audio

extract_audio

Estrae la traccia audio da un video.

Parametri:

• video_path (string, required): Percorso video
• audio_output_path (string, required): Percorso audio output (es: audio.mp3)

Esempio:

Estrai l'audio da D:\video.mp4 e salva in D:\audio.mp3

Note:

• Usa codec libmp3lame per output MP3
• Rimuove la traccia video (-vn)
• Il formato viene rilevato dall'estensione del file output

remove_audio

Rimuove completamente l'audio da un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output

Esempio:

Rimuovi l'audio da D:\video.mp4 e salva in D:\video_muto.mp4

add_audio_to_video

Aggiunge o sostituisce l'audio di un video.

Parametri:

• video_path (string, required): Percorso video
• audio_path (string, required): Percorso file audio
• output_path (string, required): Percorso output
• replace (boolean, default: true): Se true sostituisce, se false mixa

Esempio:

Sostituisci l'audio di D:\video.mp4 con D:\music.mp3 e salva in D:\video_new_audio.mp4

Note:

• Con replace: true sostituisce completamente l'audio originale
• Con replace: false mixa l'audio nuovo con quello esistente usando amix
• Il video viene copiato senza re-encoding (-c:v copy)

adjust_audio_volume

Regola il volume dell'audio in un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• volume (number, required): Moltiplicatore volume (0.5=metà, 2.0=doppio)

Esempio:

Raddoppia il volume di D:\video.mp4 e salva in D:\video_loud.mp4

generate_tone_audio

Genera un file audio con tono puro (sinusoide).

Parametri:

• output_path (string, required): Percorso audio output
• frequency (number, default: 440): Frequenza in Hz
• duration (number, required): Durata in secondi
• volume (number, default: 0.5): Volume (0.0-1.0)

Esempio:

Genera un tono di 880Hz per 5 secondi in D:\tone.mp3

✂️ Manipolazione Video

trim_video

Taglia un segmento dal video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• start_time (string, required): Tempo inizio (HH:MM:SS, es: 00:01:30)
• end_time (string, required): Tempo fine (HH:MM:SS, es: 00:02:45)
• copy_codec (boolean, default: true): Se true usa -c copy (veloce), altrimenti ri-encodifica

Esempio:

Taglia D:\video.mp4 dal minuto 1:30 al minuto 2:45 e salva in D:\clip.mp4

Note:

• copy_codec: true - Veloce, mantiene qualità originale
• copy_codec: false - Lento, ri-encodifica con libx264

concatenate_videos

Unisce più video in uno solo.

Parametri:

• input_paths (array, required): Array di percorsi video (minimo 2 file)
• output_path (string, required): Percorso output
• reencode (boolean, default: false): Se true ri-encodifica (compatibile ma lento)

Esempio:

Unisci D:\part1.mp4, D:\part2.mp4 e D:\part3.mp4 in D:\full.mp4

Note:

• reencode: false - Veloce con concat demuxer, richiede video con stesso codec/risoluzione
• reencode: true - Lento con filter_complex, funziona con qualsiasi video
• Crea automaticamente file di lista temporaneo per concat demuxer

rotate_video

Ruota un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• rotation (string, required): Angolo - "90", "180", "270", "-90"

Esempio:

Ruota D:\video.mp4 di 90 gradi e salva in D:\video_rotated.mp4

flip_video

Capovolge un video orizzontalmente o verticalmente.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• direction (string, required): "horizontal" o "vertical"

Esempio:

Capovolgi D:\video.mp4 orizzontalmente e salva in D:\video_flipped.mp4

resize_video

Ridimensiona un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• width (number, required): Larghezza (-1 per mantenere proporzioni in base all'altezza, -2 per auto)
• height (number, required): Altezza (-1 per mantenere proporzioni in base alla larghezza, -2 per auto)
• maintain_aspect (boolean, default: true): Se true mantiene le proporzioni con padding

Esempio:

Ridimensiona D:\video.mp4 a 1280x720 mantenendo proporzioni e salva in D:\video_720p.mp4

Note:

• Con maintain_aspect: true aggiunge padding nero se necessario
• Con maintain_aspect: false fa stretch del video
• Usa -1 per una dimensione per calcolare automaticamente mantenendo proporzioni

change_framerate

Modifica il frame rate di un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• fps (number, required): Nuovo frame rate (es: 24, 30, 60)

Esempio:

Cambia il frame rate di D:\video.mp4 a 60fps e salva in D:\video_60fps.mp4

change_speed

Accelera o rallenta un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• speed (number, required): Fattore velocità (0.5=lento, 2.0=veloce)
• adjust_audio (boolean, default: true): Modifica anche velocità audio

Esempio:

Rallenta D:\video.mp4 a metà velocità e salva in D:\video_slow.mp4

reverse_video

Inverte un video (riproduzione al contrario).

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• reverse_audio (boolean, default: false): Inverte anche l'audio

Esempio:

Inverti D:\video.mp4 e salva in D:\video_reverse.mp4

🎨 Filtri ed Effetti

add_watermark

Aggiunge un watermark/logo a un video.

Parametri:

• input_path (string, required): Percorso video input
• watermark_path (string, required): Percorso immagine watermark (PNG consigliato)
• output_path (string, required): Percorso video output
• position (string, default: "topright"): Posizione - "topleft", "topright", "bottomleft", "bottomright", "center"
• opacity (number, default: 1.0): Opacità (0.0-1.0)

Esempio:

Aggiungi watermark D:\logo.png in basso a destra su D:\video.mp4 con opacità 0.7

add_text

Aggiunge testo sovrapposto a un video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• text (string, required): Testo da aggiungere
• position (string, default: "bottom"): Posizione - "top", "bottom", "center"
• font_size (number, default: 24): Dimensione font
• font_color (string, default: "white"): Colore testo

Esempio:

Aggiungi il testo "Copyright 2024" in basso a D:\video.mp4, dimensione 36, colore rosso

apply_video_filter

Applica filtri video (effetti visivi).

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• filter_type (string, required): Tipo filtro - "grayscale", "blur", "brightness", "contrast", "saturation", "sharpen"
• intensity (number, default: 1.0): Intensità effetto

Esempi:

Applica filtro bianco e nero a D:\video.mp4

Applica blur intensità 5 a D:\video.mp4

Aumenta luminosità di 0.3 su D:\video.mp4

Note Intensità:

• blur: 1-20 (pixel di sfocatura)
• brightness: -1 a 1 (negativo scurisce, positivo schiarisce)
• contrast: 0-2 (1=originale)
• saturation: 0-3 (0=bianco/nero, 1=originale, 3=super saturo)

stabilize_video

Stabilizza un video mosso (riduce il tremolio).

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• shakiness (number, default: 5): Livello shake detection (1-10)

Esempio:

Stabilizza D:\video_shaky.mp4 e salva in D:\video_stable.mp4

Note: Processo in 2 passaggi, richiede più tempo.

add_fade

Aggiunge effetto fade in/out al video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• fade_in_duration (number, default: 0): Durata fade in in secondi
• fade_out_duration (number, default: 0): Durata fade out in secondi

Esempio:

Aggiungi fade in di 2 secondi e fade out di 3 secondi a D:\video.mp4

🖼️ Thumbnail e Frame

create_thumbnail

Crea una miniatura da un video.

Parametri:

• video_path (string, required): Percorso video
• output_path (string, required): Percorso immagine output (jpg, png, ecc.)
• timestamp (string, default: "00:00:01"): Timestamp (HH:MM:SS, es: 00:00:30)

Esempio:

Crea thumbnail di D:\video.mp4 al secondo 30 e salva in D:\thumb.jpg

Note:

• Estrae un singolo frame (-vframes 1)
• Il formato immagine viene rilevato dall'estensione
• Usa -ss per cercare il timestamp specificato

extract_frames

Estrae frame da video come immagini.

Parametri:

• video_path (string, required): Percorso video
• output_pattern (string, required): Pattern output (es: frame_%04d.png)
• fps (number, default: 1): Frame per secondo da estrarre
• start_time (string, default: "00:00:00"): Tempo inizio
• duration (string, optional): Durata estrazione

Esempio:

Estrai 1 frame al secondo da D:\video.mp4 e salva come D:\frames\frame_%04d.png

🎬 Creazione Video

create_video_from_images

Crea un video da una sequenza di immagini.

Parametri:

• input_pattern (string, required): Pattern immagini (es: img_%04d.png)
• output_path (string, required): Percorso video output
• fps (number, default: 25): Frame rate del video
• duration_per_image (number, optional): Durata ogni immagine in secondi

Esempio:

Crea video da immagini D:\Images\frame_%04d.jpg a 30fps, salva in D:\video.mp4

create_video_from_image

Crea un video in loop da un'immagine statica.

Parametri:

• image_path (string, required): Percorso del file immagine (jpg, png, ecc.)
• output_path (string, required): Percorso video output
• duration (number, required): Durata del video in secondi
• fps (number, default: 25): Frame rate del video
• width (number, optional): Larghezza del video (-1 per mantenere proporzioni)
• height (number, optional): Altezza del video (-1 per mantenere proporzioni)

Esempio:

Crea un video di 10 secondi da D:\immagine.jpg a 30fps, ridimensionato a 1920x1080

Note:

• Usa -loop 1 di FFmpeg per ripetere l'immagine
• Codec H.264 (libx264) per compatibilità universale
• Formato pixel yuv420p per massima compatibilità
• Opzionale: ridimensionamento con mantenimento proporzioni

create_slideshow

Crea uno slideshow con transizioni da immagini.

Parametri:

• image_paths (array, required): Array percorsi immagini
• output_path (string, required): Percorso video output
• duration_per_image (number, default: 3): Durata ogni immagine in secondi
• transition (string, default: "fade"): Tipo transizione - "fade", "wipeleft", "wiperight", "slideup", "slidedown"
• transition_duration (number, default: 1): Durata transizione in secondi

Esempio:

Crea slideshow da D:\img1.jpg, D:\img2.jpg, D:\img3.jpg con transizione fade, durata 5 secondi per immagine

create_blank_video

Crea un video vuoto con colore solido.

Parametri:

• output_path (string, required): Percorso video output
• duration (number, required): Durata in secondi
• width (number, default: 1920): Larghezza video
• height (number, default: 1080): Altezza video
• color (string, default: "black"): Colore (es: "red", "blue", "#FF0000")
• fps (number, default: 25): Frame rate

Esempio:

Crea video vuoto di 10 secondi, 1280x720, colore blu, salva in D:\blue.mp4

create_test_pattern

Crea video con pattern di test.

Parametri:

• output_path (string, required): Percorso video output
• duration (number, required): Durata in secondi
• pattern (string, default: "smptebars"): Pattern - "smptebars", "testsrc", "rgbtestsrc", "yuvtestsrc"
• width (number, default: 1920): Larghezza
• height (number, default: 1080): Altezza
• fps (number, default: 25): Frame rate

Esempio:

Crea video test pattern SMPTE bars di 5 secondi, 1920x1080 in D:\test.mp4

Pattern Disponibili:

• smptebars: SMPTE color bars (standard TV)
• testsrc: Pattern gradiente con timer
• rgbtestsrc: Pattern RGB
• yuvtestsrc: Pattern YUV

🌐 GIF e Formati Web

create_gif

Crea una GIF animata da video.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso GIF output
• start_time (string, default: "00:00:00"): Tempo inizio (HH:MM:SS)
• duration (number, optional): Durata GIF in secondi
• fps (number, default: 10): Frame rate GIF
• width (number, default: 480): Larghezza in pixel (-1 per mantenere originale)

Esempio:

Crea GIF da D:\video.mp4 dal secondo 5 per 3 secondi, 10fps, larghezza 640px

Note:

• Usa palette generation per GIF di alta qualità
• Filtro lanczos per scaling ottimale
• Riduce automaticamente dimensione file con palette ottimizzata

optimize_for_web

Ottimizza video per pubblicazione web.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• target_size_mb (number, optional): Dimensione target in MB
• max_width (number, default: 1920): Larghezza massima

Esempio:

Ottimizza D:\video.mp4 per il web, max larghezza 1280px, salva in D:\web.mp4

Ottimizzazioni Applicate:

• Codec H.264 compatibile
• Audio AAC 128kbps
• Metadata ottimizzati (faststart)
• Ridimensionamento se necessario

📱 Preset Social Media

format_for_platform

Formatta video per specifiche piattaforme social.

Parametri:

• input_path (string, required): Percorso video input
• output_path (string, required): Percorso video output
• platform (string, required): Piattaforma target

Piattaforme Supportate:

Esempio:

Formatta D:\video.mp4 per Instagram Story e salva in D:\story.mp4

💡 Esempi Pratici

Scenario 1: Creare un Video Promozionale

1. Crea slideshow da 3 immagini con transizione fade
2. Aggiungi musica di sottofondo
3. Aggiungi watermark aziendale
4. Aggiungi testo "Promo 2024" in alto
5. Formatta per Instagram Post

Scenario 2: Editing Video Base

1. Taglia video dal minuto 1 al minuto 5
2. Ruota di 90 gradi
3. Ridimensiona a 1280x720
4. Aumenta luminosità di 0.2
5. Comprimi con qualità media

Scenario 3: Creare Video da Zero

1. Crea video vuoto 10 secondi colore blu
2. Genera tono audio 440Hz per 10 secondi
3. Aggiungi audio al video
4. Aggiungi testo "Test Video"

Scenario 4: Ottimizzazione Multi-Piattaforma

1. Ottimizza video originale per web
2. Formatta copia per YouTube
3. Formatta copia per Instagram Story
4. Formatta copia per TikTok
5. Crea GIF preview di 5 secondi

🔧 Troubleshooting

Problema: "File non trovato"

Soluzione: Verifica che:

• Il percorso sia corretto
• Usi backslash doppi \\ o singoli /
• Il file esista realmente

Problema: "FFmpeg non trovato"

Soluzione:

# Verifica installazione
ffmpeg -version

# Aggiungi FFmpeg al PATH se necessario
# Pannello di controllo → Sistema → Variabili d'ambiente

Problema: Server MCP non si connette

Soluzione:

1. Verifica configurazione in claude_desktop_config.json
2. Controlla che il percorso del file server-complete.js sia corretto
3. Riavvia Claude Desktop completamente
4. Controlla i log in Settings → Developer

Problema: "Errore durante l'encoding"

Cause Comuni:

• Codec non supportato
• Formato output non compatibile
• Memoria insufficiente per video grandi

Soluzione:

• Usa reencode: true quando unisci video
• Comprimi video grandi prima di applicare filtri pesanti
• Verifica spazio su disco

Problema: Qualità video degradata

Soluzione:

• Per compressione usa quality: "high"
• Evita re-encoding multipli
• Usa -1 per mantenere proporzioni in resize
• Preferisci copy codec quando possibile

📚 Risorse Aggiuntive

Documentazione FFmpeg

• Sito ufficiale: https://ffmpeg.org/
• Documentazione: https://ffmpeg.org/documentation.html
• Wiki: https://trac.ffmpeg.org/wiki

Format Supportati

FFmpeg supporta centinaia di formati. I più comuni:

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

Codec Consigliati

• Video: H.264 (libx264) - universale
• Audio: AAC - compatibilità massima
• Web: H.264 + AAC in container MP4

🤝 Contribuire

Vuoi aggiungere nuove funzionalità? Ecco come:

1. Fork del progetto
2. Crea un branch per la feature
3. Implementa il nuovo tool in server-complete.js
4. Testa accuratamente
5. Aggiorna questo README
6. Crea una Pull Request

📝 Note sulla Versione

Versione: 2.0.0
Data: Novembre 2024
Autore: Tutorial MCP FFmpeg Server

Changelog

v2.0.0 (Novembre 2024)

• ✨ Aggiunto supporto completo creazione video
• ✨ 40+ tools totali implementati
• ✨ Preset social media
• ✨ Filtri ed effetti avanzati
• ✨ Slideshow con transizioni
• 🐛 Fix vari miglioramenti stabilità

v1.0.0 (Novembre 2024)

• 🎉 Release iniziale
• ✅ 5 tools base

⚖️ Licenza

Questo progetto è rilasciato sotto licenza MIT.

FFmpeg è software libero rilasciato sotto LGPL 2.1+ o GPL 2+.
Consulta https://ffmpeg.org/legal.html per dettagli sulla licenza FFmpeg.

🙏 Ringraziamenti

• Anthropic per il Model Context Protocol
• FFmpeg Team per l'eccellente tool multimedia
• Community Open Source per supporto e contributi

📞 Supporto

Per problemi, domande o suggerimenti:

• Apri una Issue su GitHub
• Consulta la documentazione FFmpeg
• Controlla la sezione Troubleshooting

Buon editing! 🎬✨