Il pacchetto yesilcam-studios porta Yeşilçam Studios nel tuo terminale e negli assistenti IA che parlano MCP (Model Context Protocol). Installa due comandi: yesilcam, la riga di comando per script e pipeline, e yesilcam-mcp, un server che permette a Claude Code, Claude Desktop, Cursor, VS Code, Windsurf e agli altri client MCP di usare gli studi come strumenti. La versione 0.3 copre tutti gli studi con 131 operazioni: Image, Film, Animation, Cinema, Design, Website, Fashion Try-On, Maket e AI Influencer Studio, più il tuo account e la tua libreria. Usa lo stesso account, lo stesso saldo di token e gli stessi prezzi dell’app web. Questa guida ti accompagna dall’installazione alla prima conversazione funzionante. Per una panoramica, guarda la pagina Sviluppatori.

Che cosa mi serve?

  • Node.js 18 o successivo, che include il comando npm.
  • Un account Yeşilçam Studios. Vanno bene Free, Basic e Pro; alcune funzioni richiedono Basic o Pro, esattamente come nell’app.
  • Un terminale. Per la parte con l’assistente, un client MCP come Claude Code, Claude Desktop o Cursor.

Come lo installo?

Installa il pacchetto a livello globale dal sito di Yeşilçam Studios:

npm install -g https://yesilcamstudios.com/downloads/yesilcam-studios.tgz
yesilcam --version
yesilcam --help

yesilcam --version dovrebbe stampare 0.3.0. yesilcam --help elenca i gruppi di comandi, uno per studio, e yesilcam <group> --help (per esempio yesilcam image --help) mostra i comandi e le opzioni di ciascun gruppo.

Come accedo?

Il modo consigliato è una chiave API, che crei nell’app da Account → Sviluppatore. Quando crei una chiave scegli:

  • Un nome, così più avanti riconosci le tue chiavi (per esempio "Portatile" o "Server di build").
  • Accesso: Sola lettura (saldo, prezzi, libreria, stato dei lavori) oppure Lettura e creazione, che può anche avviare lavori e spendere token.
  • Validità: 30 giorni, 90 giorni o 1 anno, oppure senza scadenza.

La chiave inizia con ysk_ e viene mostrata una sola volta, quindi copiala subito. Poi esegui yesilcam login e incollala. L’inserimento è nascosto, la chiave non viene mai stampata e viene salvata in ~/.config/yesilcam/config.json con permessi che solo il tuo utente può leggere. Controlla che abbia funzionato:

yesilcam login
yesilcam account show

Se non hai ancora una chiave, puoi accedere con email e password: yesilcam login --password. In questo caso viene salvata una sessione nello stesso file. Su un server o in CI non salvare nulla su disco: imposta la chiave nella variabile d’ambiente YESILCAM_API_KEY, oppure passala con yesilcam login --key-stdin.

Come collego Claude Code?

Basta un comando per registrare il server:

claude mcp add yesilcam -- yesilcam-mcp

Il server legge le credenziali salvate da yesilcam login, quindi non c’è nessuna chiave nel comando né nella configurazione di Claude Code.

Come collego Claude Desktop, Cursor, VS Code o Windsurf?

Questi client leggono i server MCP da un file di configurazione JSON: claude_desktop_config.json per Claude Desktop, ~/.cursor/mcp.json per Cursor e le impostazioni MCP di VS Code e Windsurf. Aggiungi questa voce:

{"mcpServers":{"yesilcam":{"command":"yesilcam-mcp","args":[]}}}

Se il file elenca già altri server, aggiungi "yesilcam" dentro l’oggetto mcpServers esistente invece di crearne un secondo. Poi riavvia il client. Non devi ricordarti niente di tutto questo: yesilcam mcp stampa gli snippet pronti per ogni client.

Posso caricare meno strumenti?

Sì. 131 strumenti sono una lista lunga, e se usi solo alcuni studi una lista più corta aiuta l’assistente a restare concentrato. Indica gli studi che ti servono in args:

{"mcpServers":{"yesilcam":{"command":"yesilcam-mcp","args":["--studios","image,film,influencer"]}}}

I nomi disponibili sono image, film, animation, cinema, design, website, fashion, maket e influencer. Gli strumenti per account e libreria vengono sempre caricati. Aggiungi "--read-only" per caricare solo gli strumenti di lettura, per esempio per un assistente che deve fare il punto sulla tua libreria ma non avviare mai lavori.

Come dovrebbe essere la mia prima conversazione?

Inizia con qualcosa di gratuito: "Qual è il mio saldo di token su Yeşilçam e quanto costa un’immagine in bozza con il mio piano?" L’assistente chiama gli strumenti del saldo e dei prezzi e ti risponde. Poi prova un lavoro piccolo: "Crea un’immagine in bozza 16:9 di un faro al tramonto. Dimmi prima il prezzo, poi salvala sulla mia scrivania." L’assistente riceve prima un preventivo e non viene addebitato nulla. Ti mostra il prezzo e solo quando sei d’accordo richiama lo strumento con l’approvazione, aspetta l’immagine e la scarica. La guida all’approvazione dei token spiega questo passaggio nel dettaglio, e le ricette per ogni studio ti mostrano cosa chiedere dopo.

Risoluzione dei problemi

  • "command not found". La cartella in cui npm mette i comandi globali non è nel tuo PATH. npm prefix -g ti mostra dove si trova; aggiungi la sua cartella bin al PATH e apri un nuovo terminale.
  • "not signed in" (codice di uscita 2). Non sono state trovate credenziali salvate. Esegui di nuovo yesilcam login, oppure controlla che YESILCAM_API_KEY sia impostata nell’ambiente in cui gira il comando.
  • L’assistente non mostra gli strumenti di Yeşilçam. Riavvia il client dopo aver modificato la configurazione. Se ancora non riesce ad avviare il server, scrivi come "command" il percorso completo del comando (lo vedi con which yesilcam-mcp su macOS e Linux).
  • La chiave viene rifiutata. Potrebbe essere scaduta o revocata. Crea una nuova chiave da Account → Sviluppatore ed esegui di nuovo yesilcam login.
  • La creazione viene rifiutata, oppure l’assistente non ha strumenti per creare. La chiave è stata creata con accesso Sola lettura, oppure il server è stato avviato con --read-only.

Domande frequenti

La CLI o il server MCP costano di più? No. Le operazioni costano esattamente quanto nell’app, con i prezzi del tuo piano, e non viene addebitato nulla prima che tu approvi un preventivo.

La mia chiave finisce nella configurazione dell’assistente? No. La configurazione indica solo il comando yesilcam-mcp; il server legge la chiave che yesilcam login ha salvato sul tuo computer.

Come esco da un computer? Esegui yesilcam logout. Rimuove le credenziali salvate da quel computer. Una chiave API continua a funzionare altrove finché non la revochi da Account → Sviluppatore.

Posso usare l’app e la CLI nello stesso momento? Sì. I lavori avviati dal terminale o da un assistente compaiono nella stessa libreria e usano lo stesso saldo dell’app.