--- title: "Servidor MCP do StemSplit: separação de stems no 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 leva a separação de stems com IA para Claude Desktop, Cursor, Cline, Windsurf e Zed via Model Context Protocol. Um único npm install: vocais + instrumental + split de 6 stems direto do chat." abstract: "TL;DR. Acabamos de publicar `stemsplit-mcp` — o servidor Model Context Protocol oficial do StemSplit. Instale uma vez com `npx`, aponte seu assistente de IA para ele e você pode rodar remoção de vocais, geração de karaokê, extração de instrumental e separação completa em 4 ou 6 stems direto do chat, em arquivos de áudio locais ou URLs do YouTube. Funciona em Claude Desktop, Cursor, Cline, Windsurf, Zed e qualquer outro cliente compatível com MCP. Licença MIT, open source no GitHub, zero infraest..." locale: "pt-BR" canonical: "https://stemsplit.io/pt-BR/blog/stemsplit-mcp-server-claude-cursor" source: "stemsplit.io" --- > **Source:** https://stemsplit.io/pt-BR/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. # Apresentando stemsplit-mcp: separação de stems com IA dentro do Claude Desktop, Cursor, Cline, Windsurf e Zed via Model Context Protocol (2026) **TL;DR.** Acabamos de publicar [**`stemsplit-mcp`**](https://www.npmjs.com/package/stemsplit-mcp) — o servidor Model Context Protocol oficial do StemSplit. Instale uma vez com `npx`, aponte seu assistente de IA para ele e você pode rodar remoção de vocais, geração de karaokê, extração de instrumental e separação completa em 4 ou 6 stems **direto do chat**, em arquivos de áudio locais **ou** URLs do YouTube. Funciona em Claude Desktop, Cursor, Cline, Windsurf, Zed e qualquer outro cliente compatível com MCP. Licença MIT, [open source no GitHub](https://github.com/StemSplit/stemsplit-mcp), zero infraestrutura pra gerenciar. A forma de um fluxo de trabalho com IA muda quando a separação de stems deixa de ser «uma API que eu chamo de um script com curl» e vira «uma coisa que meu chat sabe fazer». Este post conta o como e o porquê. --- ## O que acabou de sair [**`stemsplit-mcp` v0.2.0**](https://www.npmjs.com/package/stemsplit-mcp) no npm. Um comando pra usar: ```bash npx -y stemsplit-mcp ``` Ele fala [Model Context Protocol](https://modelcontextprotocol.io) — o padrão aberto que a Anthropic introduziu no final de 2024 para que assistentes de IA conversem com ferramentas externas por uma interface JSON-RPC uniforme. MCP já tem suporte em Claude Desktop, Cursor, Cline, Windsurf, Zed, OpenDevin, Goose e uma lista crescente de clientes. O que ele expõe: | Ferramenta | O que faz | |---|---| | `separate_stems` | Arquivo local ou URL direta de áudio → vocais, instrumental, 4 stems ou 6 stems. Faz polling até terminar e grava em disco. | | `separate_youtube` | URL do YouTube → vocais + instrumental, baixado e processado no servidor. | | `get_job` / `list_jobs` | Status e histórico de jobs. | | `get_youtube_job` / `list_youtube_jobs` | Idem, restrito ao YouTube. | | `get_balance` | Saldo de créditos restante em segundos e minutos. | | `download_stems` | Refaz as URLs presignadas frescas para qualquer job concluído. | Mais 4 resources (saldo ao vivo, jobs recentes, detalhe de job, detalhe de job do YouTube) e 4 prompts (criador de karaokê, isolador de vocais, sampler pack de seis stems, instrumental do YouTube). Referência completa no [README do GitHub](https://github.com/StemSplit/stemsplit-mcp#readme). O caso de uso principal: **jogue um path ou um URL do YouTube no chat, receba os stems**. Sem encanamento HTTP, sem código de polling, sem arquivos temporários pra limpar. --- ## Por que MCP é o formato certo para áudio Se você já integrou uma API de separação de stems — a nossa ou de qualquer outra — conhece a dança: ``` POST /jobs → retorna job_id GET /jobs/:id → polling a cada 5s até status=COMPLETED GET presigned_url → baixar cada stem para o disco ``` Três endpoints, um loop de polling, expiração nas URLs, lógica de retry para 5xx transientes. Todo time que integra áudio reescreve o mesmo código. MCP unifica isso. O truque: **arquivos de áudio não viajam pelo contexto do chat**. São grandes demais. No lugar disso, MCP troca *referências* — paths de arquivo e URLs — enquanto os bytes em si trafegam entre a sua máquina, a API do StemSplit e o Cloudflare R2. O LLM enxerga: - *«O stem de vocais está em `~/Downloads/stemsplit/job_abc123/vocals.mp3`».* e pode encadear isso na próxima ferramenta (transcrição, normalização, upload pra um projeto de DAW, o que for). Ele nunca precisa ler os 30 MB de MP3 sozinho. É também por isso que esse servidor MCP funciona com LLMs locais e modelos de contexto pequeno. O protocolo foi desenhado exatamente pra esse padrão de «faz o trabalho pesado na sua máquina e devolve uma referência». --- ## Instalação em menos de 2 minutos Você precisa de três coisas: 1. **Node.js 20+** (`node --version` pra conferir) 2. **Uma chave de API do StemSplit** — gere em [stemsplit.io/app/settings/api](https://stemsplit.io/app/settings/api) 3. **Um cliente compatível com MCP** — veja as configs por cliente abaixo Na real, você nem precisa instalar o pacote npm — a maioria dos clientes lança via `npx -y stemsplit-mcp` e faz cache no primeiro run. Se preferir instalar global: `npm install -g stemsplit-mcp`. ### Claude Desktop Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` Reinicie o Claude. O indicador MCP no rodapé da janela vai mostrar «stemsplit» com um pontinho verde quando estiver pronto. ### Cursor Adicione em `~/.cursor/mcp.json` (ou use Settings → MCP): ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` ### Cline (VS Code), Windsurf, Zed Mesma estrutura — `command`, `args`, `env`. Snippets completos por cliente no [guia de docs](/developers/guides/mcp). --- ## Como fica na prática Depois de configurado, o fluxo é só conversar. Alguns exemplos que a gente usa aqui: ### Remover vocais de um arquivo local > *«Me faz uma versão karaokê de `/Users/me/Music/song.mp3`».* O LLM escolhe `separate_stems` com `outputType=BOTH`, o servidor faz upload do arquivo, faz polling até o fim, baixa vocais + instrumental para `~/Downloads/stemsplit//` e devolve os paths locais para o assistente. O assistente te aponta o instrumental. ### De YouTube para acapella em um prompt > *«Me extrai a voz limpa de https://youtu.be/dQw4w9WgXcQ».* Escolhe `separate_youtube`. O StemSplit baixa o vídeo no servidor, faz a separação e devolve o path do stem de vocais. Sem `yt-dlp`, sem briga com rate limit. ### Split de seis stems pra sampling > *«Divide `~/Music/funk-bass.wav` nos 6 stems com a melhor qualidade».* Escolhe `separate_stems` com `outputType=SIX_STEMS` e `quality=BEST`. Você recebe drums, bass, vocals, other, piano e guitar, cada um num arquivo separado. ### Checagem prévia > *«Quantos minutos eu ainda tenho?»* Escolhe `get_balance`. Útil antes de disparar um job longo. --- ## O que tem dentro Algumas decisões técnicas que importam quando você começa a depender disso: ### Retry automático com backoff exponencial e jitter Um único 502 durante um polling de 10 minutos costumava derrubar o job inteiro. Agora: - Requisições **GET** são repetidas até 4 vezes em erros de rede, 5xx e 429 (respeitando `Retry-After`). - **POST** em endpoints de criação de job é conservador — só erros de rede que *provam que o servidor nunca viu a requisição* disparam retry. Sem cobrança em dobro acidental. - **Uploads pro R2** são repetidos até 3 vezes; o arquivo é reaberto como stream novinho a cada tentativa (web `ReadableStream`s não voltam a tocar). - **Downloads do R2** são repetidos em 5xx, mas nunca em 403 — isso significa que a URL presignada venceu e o jeito é pedir uma fresca via `get_job`. Cada retry é logado em stderr pra você ver o mecanismo trabalhando quando dá ruim. ### Validação de paths absolutos Paths relativos tipo `song.mp3` se resolviam silenciosamente contra o cwd do servidor MCP — que no Claude Desktop e no Cursor costuma ser uma raiz de sistema que o LLM não tem como saber. Agora rejeitamos paths relativos de cara com uma mensagem que diz exatamente o que fazer: *«Passe um path absoluto tipo `/Users/you/Music/song.mp3` ou um path com til tipo `~/Music/song.mp3`. Se não souber, pergunte ao usuário»*. ### Respostas de erro estruturadas Todo erro inclui um `code` lido por máquina (`INSUFFICIENT_CREDITS`, `RATE_LIMIT_EXCEEDED`, `FILE_TOO_LARGE`, `UNSUPPORTED_FORMAT`, etc.) mais uma mensagem legível e dicas pros casos comuns. O LLM não precisa fazer parsing de inglês pra entender o que aconteceu. ### Notificações de progresso Os polls são repassados como progress events do MCP. Jobs longos do YouTube mostram «10 % → 35 % → 70 % → 100 %» na UI de progresso do Claude Desktop em vez de parecerem travados. --- ## Comparativo com as opções existentes | Opção | O que você implanta | Bom para | |---|---|---| | **`stemsplit-mcp`** | Um pacote npm + uma chave de API | Fluxos em linguagem natural no Claude / Cursor / Cline / Windsurf / Zed | | **`n8n-nodes-stemsplit`** | Nó comunitário do n8n | Processamento em batch agendado ou triggerado por webhook no n8n | | **HTTP API crua** | curl / cliente próprio | Automação server-to-server, integrações sob medida | | **`demucs-onnx`** (PyPI) | Um modelo ONNX de 316 MB dentro do seu app | Casos offline / mobile / sem dependência de API | | **Demucs self-hosted** | Uma GPU, uma fila e um servidor de inferência | Cargas internas de alto volume com GPU já no orçamento | O servidor MCP é a escolha certa quando o *usuário* da ferramenta é um humano dentro de um assistente de IA. As outras opções servem quando o usuário é software. Em produção, a maioria dos times acaba combinando duas: o servidor MCP pra exploração interativa e jobs pontuais, e ou a API ou os modelos ONNX pra processamento de alto volume. --- ## Open source por design O projeto inteiro é MIT: [github.com/StemSplit/stemsplit-mcp](https://github.com/StemSplit/stemsplit-mcp). O código é compacto o bastante pra ler de uma vez — TypeScript, ~1,5 k linhas, sem dependências exóticas além do `@modelcontextprotocol/sdk` oficial e do `zod`. O helper de retry, o classificador de fonte, a lógica de polling e o mapper de erro vivem cada um no próprio arquivo com testes unitários. Se quiser dar fork pra apontar pro seu próprio backend de separação, a superfície a mexer está em [`src/client.ts`](https://github.com/StemSplit/stemsplit-mcp/blob/main/src/client.ts). O encanamento MCP em `src/index.ts` fica como está. --- ## Próximos passos Essa é a v0.2.0. No roadmap: 1. **Tool annotations** (`readOnlyHint`, `openWorldHint`) pra clientes MCP mais rígidos pularem o prompt de confirmação em ferramentas read-only como `get_balance`. 2. **Downloads de stem em paralelo** — hoje serial, 6× mais lento do que poderia em jobs de seis stems. 3. **Enumeração ao vivo de `recent-jobs`** pra clientes MCP navegarem seu histórico de jobs de forma nativa. 4. **Subscribe / notify de resources** pra progresso ao vivo em runs longos do YouTube. Acompanhe o [repo do GitHub](https://github.com/StemSplit/stemsplit-mcp) pras próximas releases — cada versão sai com entrada no CHANGELOG e release taggada no GitHub. --- ## Como o servidor stemsplit-mcp se compara a usar a REST API do StemSplit diretamente em 2026? Para fluxos interativos — *«limpa essas 5 takes que acabei de gravar»*, *«me faz uma versão karaokê desse link do YouTube»*, *«monta um sampler com esse disco de funk»* — o servidor MCP é muito melhor porque o assistente de IA cuida de toda a orquestração: classificação da fonte, upload, polling, download, recuperação de erro. Você escreve uma frase; recebe os paths. Para automação server-to-server sem humano no meio, a [REST API](https://stemsplit.io/developers/docs) é a ferramenta certa — mesma autenticação, mesmos modelos, sem runtime MCP. ## Posso usar o stemsplit-mcp com modelos locais de IA ou LLMs self-hosted em 2026? Sim — qualquer cliente compatível com MCP funciona, inclusive os apoiados em modelos locais. O servidor MCP roda como processo stdio e não sabe qual LLM está do outro lado. Testamos com Claude Desktop (Claude 4.5 Sonnet / Opus), Cursor (modelo de backend à escolha), Cline (configurável), Windsurf, Zed e Goose rodando modelos locais via Ollama. A arquitetura é propositadamente agnóstica de modelo. ## Como o servidor MCP lida com URLs do YouTube sem empacotar yt-dlp? Ele usa o endpoint server-side `/youtube-jobs` do StemSplit, que baixa o vídeo na nossa infraestrutura, roda a separação e devolve o resultado via URLs presignadas. O servidor MCP em si nunca chama `yt-dlp` localmente — isso significa zero problema de rate-limit, zero bug específico de plataforma e zero exposição legal pra quem rodaria downloads em casa. O trade-off: a URL precisa ser publicamente acessível. Vídeos privados ou restritos por idade não passam por aqui. ## A qualidade da separação pelo stemsplit-mcp é igual à do app web do StemSplit? Sim — é exatamente a mesma. O servidor MCP é um cliente fino que chama o mesmo endpoint `/api/v1/jobs` que o app web usa. Modelos, níveis de qualidade (FAST / BALANCED / BEST) e formatos de saída (MP3 / WAV / FLAC) são idênticos. A única diferença é a superfície de trigger: chat no seu assistente em vez de upload pelo navegador. ## Quais clientes MCP funcionam com o stemsplit-mcp? Qualquer cliente que suporte o transport stdio padrão do MCP. Verificados: Claude Desktop, Cursor, Cline (VS Code), Windsurf, Zed, Goose (cliente MCP open source da Block) e OpenDevin. Model Context Protocol é o padrão da Anthropic; a [lista oficial de clientes](https://modelcontextprotocol.io/clients) é a fonte de verdade conforme mais clientes ganham suporte. --- ## Experimente Se você já tem conta no StemSplit, [pega uma chave de API](https://stemsplit.io/app/settings/api) e siga o [guia de setup MCP](/developers/guides/mcp). Se não tem, [comece grátis](https://stemsplit.io/free-trial) — o tier gratuito sobra pra testar todas as ferramentas desse servidor. Se construir algo legal com isso, a gente adoraria ver: [github.com/StemSplit/stemsplit-mcp/discussions](https://github.com/StemSplit/stemsplit-mcp/discussions) ou [stemsplit.io/contact](/contact). --- *[`stemsplit-mcp`](https://www.npmjs.com/package/stemsplit-mcp) tem licença MIT. O [Model Context Protocol](https://modelcontextprotocol.io) é um padrão aberto introduzido pela Anthropic no final de 2024.* --- *This article was originally published at https://stemsplit.io/pt-BR/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.*