--- title: "StemSplit MCP 서버: Claude와 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가 Claude Desktop, Cursor, Cline, Windsurf, Zed에 AI 스템 분리를 Model Context Protocol로 가져옵니다. npm 한 줄 설치, 보컬 + 인스트루멘탈 + 6스템 분리를 채팅에서 바로." abstract: "TL;DR. StemSplit 공식 Model Context Protocol 서버인 `stemsplit-mcp` 를 막 출시했습니다. `npx`로 한 번만 띄우고 AI 어시스턴트가 이 서버를 가리키게 하면, 채팅에서 바로 보컬 제거, 노래방(MR) 만들기, 인스트루멘탈 추출, 4스템 / 6스템 분리를 실행할 수 있습니다. 로컬 오디오 파일 또는 YouTube URL 둘 다 지원합니다. Claude Desktop, Cursor, Cline, Windsurf, Zed 등 모든 MCP 호환 클라이언트에서 동작합니다. MIT 라이선스, GitHub에서 오픈소스, 관리할 인프라는 없습니다." locale: "ko" canonical: "https://stemsplit.io/ko/blog/stemsplit-mcp-server-claude-cursor" source: "stemsplit.io" --- > **Source:** https://stemsplit.io/ko/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. # stemsplit-mcp를 소개합니다: Claude Desktop · Cursor · Cline · Windsurf · Zed 안에서 Model Context Protocol로 AI 스템 분리 (2026) **TL;DR.** StemSplit 공식 Model Context Protocol 서버인 [**`stemsplit-mcp`**](https://www.npmjs.com/package/stemsplit-mcp) 를 막 출시했습니다. `npx`로 한 번만 띄우고 AI 어시스턴트가 이 서버를 가리키게 하면, **채팅에서 바로** 보컬 제거, 노래방(MR) 만들기, 인스트루멘탈 추출, 4스템 / 6스템 분리를 실행할 수 있습니다. 로컬 오디오 파일 **또는** YouTube URL 둘 다 지원합니다. Claude Desktop, Cursor, Cline, Windsurf, Zed 등 모든 MCP 호환 클라이언트에서 동작합니다. MIT 라이선스, [GitHub에서 오픈소스](https://github.com/StemSplit/stemsplit-mcp), 관리할 인프라는 없습니다. 스템 분리가 "스크립트에서 curl로 호출하는 API"가 아니라 "내 채팅이 알아서 해 주는 일"로 바뀌면, AI 워크플로의 형태 자체가 달라집니다. 이 글은 그 방법과 이유를 정리합니다. --- ## 무엇이 나왔나 npm에 [**`stemsplit-mcp` v0.2.0**](https://www.npmjs.com/package/stemsplit-mcp). 한 줄이면 사용할 수 있습니다. ```bash npx -y stemsplit-mcp ``` 이 서버는 [Model Context Protocol](https://modelcontextprotocol.io)을 말합니다. 2024년 말 Anthropic이 도입한 오픈 표준으로, AI 어시스턴트가 외부 도구와 균일한 JSON-RPC 인터페이스로 대화할 수 있게 합니다. MCP는 이제 Claude Desktop, Cursor, Cline, Windsurf, Zed, OpenDevin, Goose 등 점점 늘어나는 클라이언트에서 지원됩니다. 서버가 제공하는 도구: | 도구 | 하는 일 | |---|---| | `separate_stems` | 로컬 파일 또는 직접 오디오 URL → 보컬, 인스트, 4스템 또는 6스템. 완료까지 폴링하고 디스크에 저장합니다. | | `separate_youtube` | YouTube URL → 보컬 + 인스트. 서버 측에서 다운로드해 처리합니다. | | `get_job` / `list_jobs` | 작업 상태와 히스토리. | | `get_youtube_job` / `list_youtube_jobs` | 위와 동일, YouTube 작업 전용. | | `get_balance` | 남은 크레딧을 초·분 단위로 반환. | | `download_stems` | 완료된 작업의 프리사인 URL을 새로 받아 다시 다운로드합니다. | 여기에 4개의 리소스(실시간 잔액, 최근 작업, 작업 상세, YouTube 작업 상세)와 4개의 프롬프트(노래방 메이커, 보컬 분리, 6스템 샘플러 팩, YouTube 인스트)도 포함됩니다. 전체 레퍼런스는 [GitHub README](https://github.com/StemSplit/stemsplit-mcp#readme)에 있습니다. 핵심 사용 시나리오는 **채팅에 경로 또는 YouTube URL을 던지면 스템이 돌아오는 것**입니다. HTTP 배관도, 폴링 코드도, 정리할 임시 파일도 없습니다. --- ## 왜 MCP가 오디오에 적합한가 스템 분리 API를 통합해 본 분이라면 — 우리 것이든 다른 곳이든 — 같은 춤을 알고 있을 겁니다. ``` POST /jobs → job_id 반환 GET /jobs/:id → 5초마다 폴링, status=COMPLETED 까지 GET presigned_url → 각 스템을 디스크로 다운로드 ``` 엔드포인트 3개, 폴링 루프 하나, 만료되는 URL, 일시적 5xx에 대한 재시도 로직. 오디오를 붙이는 모든 팀이 같은 코드를 다시 씁니다. MCP는 이것을 한 번에 흡수합니다. 핵심: **오디오 파일은 채팅 컨텍스트로 흐르지 않습니다**. 파일이 너무 큽니다. 대신 MCP는 *참조*(파일 경로와 URL)만 교환하고, 실제 바이트는 여러분의 머신, StemSplit API, Cloudflare R2 사이를 직접 스트리밍합니다. LLM이 보는 건 다음과 같은 한 줄뿐입니다: - *"보컬 스템은 `~/Downloads/stemsplit/job_abc123/vocals.mp3`에 있습니다."* LLM은 이 정보를 다음 도구(전사, 노멀라이즈, DAW 프로젝트로 업로드 등)에 그대로 넘길 수 있습니다. 30 MB짜리 MP3를 LLM이 직접 읽을 일은 없습니다. 이 MCP 서버가 로컬 LLM과 작은 컨텍스트 모델에서도 잘 동작하는 이유이기도 합니다. 프로토콜 자체가 "무거운 일은 네 머신에서 하고 참조만 돌려줘" 패턴을 위해 설계됐기 때문입니다. --- ## 2분이면 설치 끝 세 가지가 필요합니다. 1. **Node.js 20 이상** (`node --version`으로 확인) 2. **StemSplit API 키** — [stemsplit.io/app/settings/api](https://stemsplit.io/app/settings/api) 에서 발급 3. **MCP 호환 클라이언트** — 클라이언트별 설정은 아래 참고 사실 npm 패키지를 직접 설치할 필요는 없습니다. 대부분의 클라이언트가 `npx -y stemsplit-mcp`로 띄우고 첫 실행 때 캐시합니다. 전역 설치를 원하면 `npm install -g stemsplit-mcp`. ### Claude Desktop macOS는 `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows는 `%APPDATA%\Claude\claude_desktop_config.json` 을 편집: ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` Claude를 재시작하면 창 하단의 MCP 표시에 녹색 점과 함께 "stemsplit"이 나타납니다. ### Cursor `~/.cursor/mcp.json` (또는 Settings → MCP)에 추가: ```json { "mcpServers": { "stemsplit": { "command": "npx", "args": ["-y", "stemsplit-mcp"], "env": { "STEMSPLIT_API_KEY": "sk_live_..." } } } } ``` ### Cline (VS Code), Windsurf, Zed 구조는 동일합니다 — `command`, `args`, `env`. 클라이언트별 전체 스니펫은 [docs 가이드](/developers/guides/mcp)에 있습니다. --- ## 실제로는 이렇게 보입니다 설정이 끝나면 워크플로는 **대화하기만 하면 됩니다**. 저희가 쓰는 예시 몇 개: ### 로컬 파일에서 보컬 제거 > *"`/Users/me/Music/song.mp3`의 노래방(MR) 버전을 만들어줘."* LLM이 `separate_stems`를 `outputType=BOTH`로 선택합니다. 서버는 파일을 업로드하고, 끝까지 폴링하고, 보컬 + 인스트를 `~/Downloads/stemsplit//`에 받은 다음 로컬 경로를 어시스턴트에게 전달합니다. 어시스턴트가 인스트 경로를 안내해 줍니다. ### YouTube → 아카펠라를 한 번에 > *"https://youtu.be/dQw4w9WgXcQ 에서 깔끔한 보컬만 뽑아줘."* `separate_youtube`를 선택합니다. StemSplit이 서버 측에서 영상을 받아 분리를 돌리고, 보컬 스템의 로컬 경로를 돌려줍니다. `yt-dlp`도, 레이트 리밋 줄다리기도 없습니다. ### 샘플링용 6스템 분리 > *"`~/Music/funk-bass.wav`을 최고 품질로 6스템으로 분리해줘."* `separate_stems`를 `outputType=SIX_STEMS`, `quality=BEST`로 선택합니다. drums, bass, vocals, other, piano, guitar가 각각 별도 파일로 저장됩니다. ### 사전 점검 > *"몇 분 남았어?"* `get_balance`를 선택합니다. 긴 작업을 돌리기 전에 확인하기 좋습니다. --- ## 박스 안에는 무엇이 서버에 의존하기 시작했을 때 차이를 만드는 결정들: ### 지수 백오프 + 지터가 적용된 자동 재시도 10분짜리 폴링 도중 우연히 502 한 번 뜨면 작업 전체가 실패하던 시절이 있었습니다. 이제는: - **GET** 요청은 네트워크 오류, 5xx, 429에 대해 최대 4번 재시도하며 `Retry-After`를 존중합니다. - 작업 생성 **POST**는 보수적입니다. *서버가 요청을 본 적이 없음이 증명되는* 네트워크 오류만 재시도 대상이라 이중 청구가 발생하지 않습니다. - **R2 업로드**는 최대 3번 재시도합니다. 각 시도마다 파일을 새 스트림으로 다시 엽니다 (웹 `ReadableStream`은 되감기가 안 되니까). - **R2 다운로드**는 5xx에서는 재시도하지만 403에서는 안 합니다 — 프리사인 URL이 만료된 경우라 `get_job`으로 새 URL을 받는 게 정답입니다. 모든 재시도는 stderr에 로깅되어, 문제가 생겼을 때 동작을 바로 확인할 수 있습니다. ### 절대 경로 검증 `song.mp3` 같은 상대 경로는 예전엔 MCP 서버의 작업 디렉터리를 기준으로 조용히 해석됐습니다. Claude Desktop과 Cursor에서는 보통 시스템 루트라 LLM이 알 길이 없었죠. 이제 상대 경로는 즉시 거부하고, LLM에게 정확히 무엇을 해야 하는지 알려줍니다: *"`/Users/you/Music/song.mp3` 같은 절대 경로나 `~/Music/song.mp3` 같은 틸드 경로를 넘기세요. 모르면 사용자에게 물어보세요."* ### 구조화된 오류 응답 모든 오류에는 기계 가독 `code`(`INSUFFICIENT_CREDITS`, `RATE_LIMIT_EXCEEDED`, `FILE_TOO_LARGE`, `UNSUPPORTED_FORMAT` 등), 사람 가독 메시지, 자주 발생하는 케이스를 위한 힌트가 포함됩니다. LLM이 무엇이 잘못됐는지 알기 위해 영어를 파싱할 필요가 없습니다. ### 진행률 알림 폴링은 MCP progress 이벤트로 전달됩니다. 긴 YouTube 작업이 Claude Desktop의 진행률 UI에 "10% → 35% → 70% → 100%"로 표시되어 멈춘 것처럼 보이지 않습니다. --- ## 기존 옵션들과의 비교 | 옵션 | 배포 대상 | 적합한 경우 | |---|---|---| | **`stemsplit-mcp`** | npm 패키지 1개 + API 키 | Claude / Cursor / Cline / Windsurf / Zed 안에서 자연어 워크플로 | | **`n8n-nodes-stemsplit`** | n8n 커뮤니티 노드 | n8n에서 스케줄 또는 웹훅 기반 배치 처리 | | **Raw HTTP API** | curl / 직접 만든 클라이언트 | 서버 간 자동화, 커스텀 통합 | | **`demucs-onnx`** (PyPI) | 앱에 316MB ONNX 모델 동봉 | 오프라인 / 모바일 / API 의존 없는 케이스 | | **Self-hosted Demucs** | GPU, 큐, 추론 서버 | 이미 GPU를 보유한 사내 고볼륨 워크로드 | 도구의 *사용자*가 AI 어시스턴트 안의 사람이라면 MCP 서버가 정답입니다. 사용자가 소프트웨어라면 다른 옵션들이 정답입니다. 실제 프로덕션에서는 보통 두 가지를 함께 씁니다: 인터랙티브 탐색과 일회성 작업에는 MCP 서버, 고볼륨 처리에는 API 또는 ONNX 모델. --- ## 설계상 오픈소스 프로젝트 전체가 MIT입니다: [github.com/StemSplit/stemsplit-mcp](https://github.com/StemSplit/stemsplit-mcp). 코드 크기는 한 자리에 다 읽을 만한 정도 — TypeScript 약 1.5k 라인, 공식 `@modelcontextprotocol/sdk`와 `zod` 외에는 외부 의존 없음. 재시도 헬퍼, 소스 분류, 폴링 로직, 오류 매퍼가 각자 파일과 유닛 테스트로 분리돼 있습니다. 자체 분리 백엔드로 포크하려면 변경 면이 [`src/client.ts`](https://github.com/StemSplit/stemsplit-mcp/blob/main/src/client.ts)에 모여 있습니다. `src/index.ts`의 MCP 배관은 그대로 둬도 됩니다. --- ## 다음 단계 이번이 v0.2.0입니다. 로드맵: 1. **툴 어노테이션** (`readOnlyHint`, `openWorldHint`) — 엄격한 MCP 클라이언트가 `get_balance` 같은 읽기 전용 도구의 확인 프롬프트를 건너뛸 수 있도록. 2. **스템 병렬 다운로드** — 현재 직렬이라 6스템 작업에서 6배 느립니다. 3. **`recent-jobs`의 라이브 enumeration** — MCP 클라이언트가 작업 히스토리를 네이티브로 탐색. 4. **리소스 subscribe / notify** — 긴 YouTube 작업의 실시간 진행률 표시. [GitHub 저장소](https://github.com/StemSplit/stemsplit-mcp)에서 새 릴리스를 받아보세요. 모든 버전은 CHANGELOG 항목과 태그된 GitHub Release를 함께 출시합니다. --- ## 2026년에 stemsplit-mcp 서버는 StemSplit REST API를 직접 호출하는 것과 비교해 어떤가요? 인터랙티브 워크플로 — *"방금 녹음한 5트랙 정리해줘"*, *"이 YouTube 링크 노래방 버전 만들어줘"*, *"이 펑크 앨범으로 샘플러 구성해줘"* — 에서는 MCP 서버가 훨씬 우수합니다. AI 어시스턴트가 소스 분류, 업로드, 폴링, 다운로드, 오류 회복 같은 오케스트레이션을 전부 처리합니다. 한 문장이면 파일 경로가 돌아옵니다. 사람이 끼지 않는 서버 간 자동화에는 [REST API](https://stemsplit.io/developers/docs)가 적합합니다 — 인증과 모델은 동일하지만 MCP 런타임이 필요하지 않습니다. ## 2026년에 로컬 AI 모델이나 셀프 호스팅 LLM에서도 stemsplit-mcp를 쓸 수 있나요? 네 — MCP 호환 클라이언트라면 무엇이든 동작합니다. 로컬 모델 기반 클라이언트도 포함입니다. MCP 서버는 stdio 프로세스라 반대편 LLM이 무엇인지 알지 못합니다. Claude Desktop(Claude 4.5 Sonnet / Opus), Cursor(백엔드 모델 임의), Cline(설정 가능), Windsurf, Zed, 그리고 Ollama로 로컬 모델을 돌리는 Goose에서 동작을 확인했습니다. 아키텍처는 의도적으로 모델 비종속입니다. ## yt-dlp를 번들링하지 않고 어떻게 YouTube URL을 처리하나요? StemSplit의 서버 측 `/youtube-jobs` 엔드포인트를 사용합니다. 영상은 저희 인프라에서 다운로드해 분리한 뒤 프리사인 URL로 결과를 노출합니다. MCP 서버 자체는 `yt-dlp`를 로컬에서 호출하지 않으므로 레이트 리밋 문제, 플랫폼별 설치 실패, 로컬 다운로드에 따르는 법적 위험이 모두 사라집니다. 트레이드오프는 URL이 공개 접근 가능해야 한다는 점입니다. 비공개 영상이나 연령 제한 영상은 이 경로로는 처리되지 않습니다. ## stemsplit-mcp로 분리한 결과 품질은 StemSplit 웹 앱과 같나요? 정확히 같습니다. MCP 서버는 웹 앱이 호출하는 `/api/v1/jobs` 엔드포인트를 그대로 호출하는 얇은 클라이언트입니다. 모델, 품질 티어(FAST / BALANCED / BEST), 출력 포맷(MP3 / WAV / FLAC)이 동일합니다. 차이는 트리거 표면뿐 — 브라우저 업로드 대신 AI 어시스턴트에서의 채팅입니다. ## stemsplit-mcp는 어떤 MCP 클라이언트와 호환되나요? 표준 MCP stdio 전송을 지원하는 모든 클라이언트. 검증된 클라이언트: Claude Desktop, Cursor, Cline (VS Code), Windsurf, Zed, Goose (Block의 오픈소스 MCP 클라이언트), OpenDevin. Model Context Protocol은 Anthropic의 표준이며, 새 클라이언트가 추가될 때마다 [공식 클라이언트 목록](https://modelcontextprotocol.io/clients)이 단일 소스 오브 트루스가 됩니다. --- ## 직접 써 보세요 StemSplit 계정이 있다면 [API 키를 발급](https://stemsplit.io/app/settings/api)하고 [MCP 설정 가이드](/developers/guides/mcp)를 따르세요. 없다면 [무료로 시작](https://stemsplit.io/free-trial). 무료 티어로 이 서버의 모든 도구를 충분히 시험해볼 수 있습니다. 이걸로 멋진 걸 만드셨다면 꼭 보여주세요: [github.com/StemSplit/stemsplit-mcp/discussions](https://github.com/StemSplit/stemsplit-mcp/discussions) 또는 [stemsplit.io/contact](/contact). --- *[`stemsplit-mcp`](https://www.npmjs.com/package/stemsplit-mcp)는 MIT 라이선스입니다. [Model Context Protocol](https://modelcontextprotocol.io)은 Anthropic이 2024년 말에 도입한 오픈 표준입니다.* --- *This article was originally published at https://stemsplit.io/ko/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.*