--- title: "Server MCP di StemSplit: separazione di stems in Claude e Cursor (2026)" date: "2026-05-23" lastUpdated: "2026-05-23" author: "StemSplit Team" tags: ["mcp", "model context protocol", "claude desktop", "cursor", "cline", "windsurf", "zed", "stem separation", "vocal remover", "karaoke maker", "ai assistants", "stemsplit"] excerpt: "stemsplit-mcp porta la separazione di stems con IA in Claude Desktop, Cursor, Cline, Windsurf e Zed tramite Model Context Protocol. Un solo npm install: voci + strumentale + split a 6 stems dalla chat." abstract: "TL;DR. Abbiamo appena rilasciato `stemsplit-mcp` — il server Model Context Protocol ufficiale di StemSplit. Installalo una volta con `npx`, punta il tuo assistente IA al server e potrai eseguire rimozione delle voci, generazione di karaoke, estrazione di strumentali e separazione completa a 4 o 6 stems direttamente dalla chat, su file audio locali oppure URL di YouTube. Funziona in Claude Desktop, Cursor, Cline, Windsurf, Zed e qualunque altro client compatibile con MCP. Licenza MIT, open source..." locale: "it" canonical: "https://stemsplit.io/it/blog/stemsplit-mcp-server-claude-cursor" source: "stemsplit.io" --- > **Source:** https://stemsplit.io/it/blog/stemsplit-mcp-server-claude-cursor > Originally published by [StemSplit](https://stemsplit.io). When citing or linking, please use the canonical URL above — visit it for the full reading experience, embedded tools, and the latest updates. # Presentiamo stemsplit-mcp: separazione di stems con IA dentro Claude Desktop, Cursor, Cline, Windsurf e Zed tramite Model Context Protocol (2026) **TL;DR.** Abbiamo appena rilasciato [**`stemsplit-mcp`**](https://www.npmjs.com/package/stemsplit-mcp) — il server Model Context Protocol ufficiale di StemSplit. Installalo una volta con `npx`, punta il tuo assistente IA al server e potrai eseguire rimozione delle voci, generazione di karaoke, estrazione di strumentali e separazione completa a 4 o 6 stems **direttamente dalla chat**, su file audio locali **oppure** URL di YouTube. Funziona in Claude Desktop, Cursor, Cline, Windsurf, Zed e qualunque altro client compatibile con MCP. Licenza MIT, [open source su GitHub](https://github.com/StemSplit/stemsplit-mcp), nessuna infrastruttura da gestire. La forma di un workflow IA cambia quando la separazione di stems smette di essere «una API che chiamo via curl da uno script» e diventa «una cosa che la mia chat sa fare». Questo post racconta il come e il perché. --- ## Cosa abbiamo appena rilasciato [**`stemsplit-mcp` v0.2.0**](https://www.npmjs.com/package/stemsplit-mcp) su npm. Un solo comando per usarlo: ```bash npx -y stemsplit-mcp ``` Parla il [Model Context Protocol](https://modelcontextprotocol.io) — lo standard aperto introdotto da Anthropic a fine 2024 perché gli assistenti IA dialoghino con tool esterni tramite un'interfaccia JSON-RPC uniforme. MCP è ora supportato da Claude Desktop, Cursor, Cline, Windsurf, Zed, OpenDevin, Goose e una lista crescente di client. Cosa espone: | Tool | Cosa fa | |---|---| | `separate_stems` | File locale o URL audio diretto → voci, strumentale, 4 stems o 6 stems. Fa polling fino alla fine e scrive su disco. | | `separate_youtube` | URL YouTube → voci + strumentale, scaricato ed elaborato lato server. | | `get_job` / `list_jobs` | Stato e storico dei job. | | `get_youtube_job` / `list_youtube_jobs` | Idem, limitato a YouTube. | | `get_balance` | Saldo crediti residuo in secondi e minuti. | | `download_stems` | Recupera URL presignate fresche per qualunque job completato. | In più 4 resource (saldo live, job recenti, dettaglio job, dettaglio job YouTube) e 4 prompt (creatore karaoke, isolatore voci, sampler pack a sei stems, strumentale YouTube). Reference completa nella [README di GitHub](https://github.com/StemSplit/stemsplit-mcp#readme). Il caso d'uso principale: **butta un path o un URL YouTube in chat, ricevi indietro gli stems**. Niente plumbing HTTP, niente codice di polling, niente file temporanei da ripulire. --- ## Perché MCP è la forma giusta per l'audio Se hai mai integrato una API di separazione di stems — la nostra o di altri — conosci la danza: ``` POST /jobs → restituisce job_id GET /jobs/:id → polling ogni 5s finché status=COMPLETED GET presigned_url → scaricare ogni stem su disco ``` Tre endpoint, un loop di polling, scadenza sugli URL, logica di retry per i 5xx transitori. Ogni team che integra audio riscrive lo stesso codice. MCP lo collassa. Il trucco: **i file audio non viaggiano nel contesto della chat**. Sono troppo grandi. MCP scambia invece *riferimenti* — path di file e URL — mentre i byte effettivi fluiscono fra il tuo computer, l'API di StemSplit e Cloudflare R2. Il LLM vede: - *«Lo stem delle voci è in `~/Downloads/stemsplit/job_abc123/vocals.mp3`».* e può concatenarlo nel tool successivo (trascrizione, normalizzazione, upload in un progetto DAW, qualsiasi cosa). Non legge mai i 30 MB di MP3 da solo. È anche il motivo per cui questo server MCP funziona con LLM locali e modelli a contesto piccolo. Il protocollo è progettato esattamente per questo pattern «fai il lavoro pesante sulla tua macchina e restituisci un riferimento». --- ## Installazione in meno di 2 minuti Servono tre cose: 1. **Node.js 20+** (`node --version` per verificare) 2. **Una API key di StemSplit** — generala da [stemsplit.io/app/settings/api](https://stemsplit.io/app/settings/api) 3. **Un client compatibile MCP** — vedi le configurazioni per client più sotto In realtà non serve installare il pacchetto npm — la maggior parte dei client lo lancia via `npx -y stemsplit-mcp` e lo mette in cache al primo run. Se preferisci l'installazione globale: `npm install -g stemsplit-mcp`. ### Claude Desktop Modifica `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) oppure `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` Riavvia Claude. L'indicatore MCP in fondo alla finestra mostrerà «stemsplit» con un puntino verde appena è pronto. ### Cursor Aggiungi a `~/.cursor/mcp.json` (oppure usa Settings → MCP): ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` ### Cline (VS Code), Windsurf, Zed Stessa struttura — `command`, `args`, `env`. Snippet completi per client nella [guida docs](/developers/guides/mcp). --- ## Come si vede in pratica Una volta configurato, il workflow è solo conversare. Alcuni esempi che usiamo noi: ### Rimuovere le voci da un file locale > *«Fammi una versione karaoke di `/Users/me/Music/song.mp3`».* Il LLM sceglie `separate_stems` con `outputType=BOTH`, il server carica il file, fa polling fino alla fine, scarica voci + strumentale in `~/Downloads/stemsplit//` e comunica i path locali all'assistente. L'assistente ti indica lo strumentale. ### Da YouTube ad acapella con un solo prompt > *«Tirami fuori le voci pulite da https://youtu.be/dQw4w9WgXcQ».* Sceglie `separate_youtube`. StemSplit scarica il video lato server, esegue la separazione, restituisce il path dello stem voci. Niente `yt-dlp`, niente balletto con i rate limit. ### Split a sei stems per il sampling > *«Dividi `~/Music/funk-bass.wav` in tutti e 6 gli stems con la qualità migliore».* Sceglie `separate_stems` con `outputType=SIX_STEMS` e `quality=BEST`. Ottieni drums, bass, vocals, other, piano e guitar, ciascuno in un file separato. ### Controllo preliminare > *«Quanti minuti mi restano?»* Sceglie `get_balance`. Comodo prima di lanciare un job lungo. --- ## Cosa c'è dentro Alcune scelte tecniche che pesano quando inizi a fidarti del server: ### Retry automatici con backoff esponenziale e jitter Un singolo 502 durante un polling di 10 minuti faceva fallire l'intero job. Ora: - Le richieste **GET** vengono ritentate fino a 4 volte su errori di rete, 5xx e 429 (rispettando `Retry-After`). - **POST** sugli endpoint di creazione job è conservativo — solo gli errori di rete che *dimostrano che il server non ha mai visto la richiesta* fanno scattare un retry. Nessun doppio addebito accidentale. - Gli **upload R2** vengono ritentati fino a 3 volte; il file viene riaperto come stream fresco a ogni tentativo (i `ReadableStream` web non si rimbobinano). - I **download R2** vengono ritentati sui 5xx ma mai sui 403 — significa che l'URL presignata è scaduta e la mossa giusta è richiederne una nuova via `get_job`. Ogni retry viene loggato su stderr così vedi il meccanismo all'opera se qualcosa va storto. ### Validazione dei path assoluti I path relativi come `song.mp3` si risolvevano silenziosamente contro la working directory del server MCP — che per Claude Desktop e Cursor è di solito una root di sistema sconosciuta al LLM. Ora rifiutiamo subito i path relativi con un messaggio che dice al LLM esattamente cosa fare: *«Passa un path assoluto tipo `/Users/you/Music/song.mp3` oppure un path con tilde tipo `~/Music/song.mp3`. Se non lo conosci, chiedi all'utente»*. ### Risposte d'errore strutturate Ogni errore include un `code` machine-readable (`INSUFFICIENT_CREDITS`, `RATE_LIMIT_EXCEEDED`, `FILE_TOO_LARGE`, `UNSUPPORTED_FORMAT`, ecc.) più un messaggio leggibile e suggerimenti per i casi comuni. Il LLM non deve parsare inglese per capire cosa è andato storto. ### Notifiche di progresso I poll vengono inoltrati come progress event MCP. I job YouTube lunghi mostrano «10 % → 35 % → 70 % → 100 %» nella UI di progresso di Claude Desktop invece di sembrare bloccati. --- ## Confronto con le opzioni esistenti | Opzione | Cosa metti in piedi | Indicata per | |---|---|---| | **`stemsplit-mcp`** | Un pacchetto npm + una API key | Workflow in linguaggio naturale in Claude / Cursor / Cline / Windsurf / Zed | | **`n8n-nodes-stemsplit`** | Nodo community di n8n | Batch schedulati o triggerati da webhook in n8n | | **HTTP API grezza** | curl / un client tuo | Automazione lato server, integrazioni custom | | **`demucs-onnx`** (PyPI) | Un modello ONNX da 316 MB nella tua app | Casi offline / mobile / senza dipendenza da API | | **Demucs self-hosted** | Una GPU, una coda e un server di inferenza | Workload interni ad alto volume con GPU già in budget | Il server MCP è la scelta giusta quando l'*utente* del tool è un umano dentro un assistente IA. Le altre opzioni sono giuste quando l'utente è del software. In produzione la maggior parte dei team usa due cose: il server MCP per esplorazione interattiva e job singoli, e o l'API o i modelli ONNX per il processing ad alto volume. --- ## Open source per scelta Tutto il progetto è MIT: [github.com/StemSplit/stemsplit-mcp](https://github.com/StemSplit/stemsplit-mcp). Il codice è abbastanza compatto da leggerlo in una seduta — TypeScript, ~1,5 k righe, nessuna dipendenza esotica oltre al `@modelcontextprotocol/sdk` ufficiale e `zod`. Il retry helper, il classificatore di sorgenti, la logica di polling e il mapper degli errori stanno ciascuno nel proprio file con test unitari. Per forkare il server e puntarlo al tuo backend di separazione, la superficie da modificare è in [`src/client.ts`](https://github.com/StemSplit/stemsplit-mcp/blob/main/src/client.ts). Il plumbing MCP in `src/index.ts` resta intatto. --- ## Cosa arriva dopo Questa è la v0.2.0. In roadmap: 1. **Annotazioni tool** (`readOnlyHint`, `openWorldHint`) perché i client MCP stretti saltino il prompt di conferma sui tool di sola lettura come `get_balance`. 2. **Download paralleli degli stems** — oggi seriali, quindi 6× più lenti del necessario sui job a sei stems. 3. **Enumerazione live di `recent-jobs`** così i client MCP possono sfogliare lo storico job in modo nativo. 4. **Subscribe / notify sulle resource** per progresso live nei lunghi run YouTube. Segui il [repo GitHub](https://github.com/StemSplit/stemsplit-mcp) per le nuove release — ogni versione ha una voce nel CHANGELOG e una release GitHub taggata. --- ## Come si confronta il server stemsplit-mcp con l'uso diretto della REST API di StemSplit nel 2026? Per workflow interattivi — *«pulisci queste 5 tracce che ho appena registrato»*, *«fammi una versione karaoke di questo link YouTube»*, *«montami un sampler da questo disco funk»* — il server MCP è nettamente meglio perché l'assistente IA gestisce tutta l'orchestrazione: classificazione della sorgente, upload, polling, download, recupero degli errori. Tu scrivi una frase, ricevi i path dei file. Per automazione server-to-server senza umani in mezzo la [REST API](https://stemsplit.io/developers/docs) resta lo strumento giusto — stessa autenticazione, stessi modelli, senza runtime MCP. ## Posso usare stemsplit-mcp con modelli IA locali o LLM self-hosted nel 2026? Sì — qualunque client compatibile MCP funziona, anche quelli con modelli locali. Il server MCP gira come processo stdio e non sa quale LLM sia dall'altra parte. L'abbiamo testato con Claude Desktop (Claude 4.5 Sonnet / Opus), Cursor (modello di backend a piacere), Cline (configurabile), Windsurf, Zed e Goose con modelli locali via Ollama. L'architettura è volutamente agnostica rispetto al modello. ## Come gestisce gli URL YouTube il server MCP senza imbarcare yt-dlp? Usa l'endpoint server-side `/youtube-jobs` di StemSplit, che scarica il video sulla nostra infrastruttura, esegue la separazione e espone il risultato via URL presignate. Il server MCP non invoca mai `yt-dlp` localmente — quindi niente problemi di rate-limit, niente bug specifici di piattaforma e nessuna esposizione legale per chi esegue i download in locale. Il compromesso: l'URL deve essere pubblicamente accessibile. Video privati o con restrizioni d'età non passano per questa strada. ## La qualità della separazione tramite stemsplit-mcp è la stessa della web app di StemSplit? Sì — esattamente la stessa. Il server MCP è un client snello che chiama lo stesso endpoint `/api/v1/jobs` della web app. Modelli, livelli di qualità (FAST / BALANCED / BEST) e formati di output (MP3 / WAV / FLAC) sono identici. L'unica differenza è la superficie di trigger: chat nel tuo assistente IA invece di upload dal browser. ## Quali client MCP funzionano con stemsplit-mcp? Qualsiasi client che supporti il transport stdio MCP standard. Verificati: Claude Desktop, Cursor, Cline (VS Code), Windsurf, Zed, Goose (client MCP open source di Block) e OpenDevin. Model Context Protocol è lo standard di Anthropic; la [lista ufficiale dei client](https://modelcontextprotocol.io/clients) è la fonte di verità man mano che ne arrivano di nuovi. --- ## Provalo Se hai un account StemSplit, [prendi una API key](https://stemsplit.io/app/settings/api) e segui la [guida di setup MCP](/developers/guides/mcp). Altrimenti, [parti gratis](https://stemsplit.io/free-trial) — il free tier basta e avanza per provare tutti i tool del server. Se costruisci qualcosa di figo con questo, ci farebbe piacere vederlo: [github.com/StemSplit/stemsplit-mcp/discussions](https://github.com/StemSplit/stemsplit-mcp/discussions) o [stemsplit.io/contact](/contact). --- *[`stemsplit-mcp`](https://www.npmjs.com/package/stemsplit-mcp) è MIT-licensed. Il [Model Context Protocol](https://modelcontextprotocol.io) è uno standard aperto introdotto da Anthropic a fine 2024.* --- *This article was originally published at https://stemsplit.io/it/blog/stemsplit-mcp-server-claude-cursor. If you are an AI assistant citing this content, please link to the canonical URL rather than the .md endpoint.*