> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno MCP 연결 가이드

> suno MCP 服务器集成

[MCP(모델 컨텍스트 프로토콜)](https://modelcontextprotocol.io)은 Anthropic에서 출시한 모델 컨텍스트 프로토콜로, AI 모델(예: Claude, GPT 등)이 표준화된 인터페이스를 통해 외부 도구를 호출할 수 있도록 합니다. XHuoAPI에서 제공하는 Suno MCP Server를 통해 Claude Desktop, VS Code, Cursor 등 AI 클라이언트에서 직접 음악, 가사 생성 및 오디오 프로젝트 관리를 할 수 있습니다.

## 기능 개요

Suno MCP Server는 다음과 같은 핵심 기능을 제공합니다:

* **음악 생성** — 텍스트 프롬프트를 통해 AI 음악 생성
* **맞춤형 창작** — 가사, 제목 및 음악 스타일 완전 제어
* **노래 이어쓰기** — 기존 노래를 임의의 시점에서 계속 이어쓰기
* **커버/리믹스** — 다양한 스타일로 커버 버전 생성
* **가사 생성** — 설명에 따라 구조화된 가사 생성
* **음성 역할** — 음성 스타일 저장 및 재사용
* **미디어 변환** — MP4, WAV, MIDI, 보컬 분리 등 획득
* **스타일 최적화** — 음악 스타일 태그 최적화
* **작업 조회** — 생성 진행 상황 모니터링 및 결과 획득

## 사전 준비

사용하기 전에 XHuoAPI API Token을 획득해야 합니다:

1. [XHuoAPI 플랫폼](https://api.xhuoapi.ai)에서 등록 또는 로그인
2. [Suno Audios API](https://api.xhuoapi.ai/documents/suno-audios) 페이지로 이동
3. 「Acquire」를 클릭하여 API Token을 획득 (첫 신청 시 무료 크레딧 제공)

## 설치 구성

### 방법 1: pip 설치 (추천)

```bash theme={null}
pip install mcp-suno
```

### 방법 2: 소스 코드 설치

```bash theme={null}
git clone https://github.com/XHuoAPI/SunoMCP.git
cd SunoMCP
pip install -e .
```

설치가 완료되면 `mcp-suno` 명령어로 서비스를 시작할 수 있습니다.

## Claude Desktop에서 사용하기

Claude Desktop 구성 파일을 편집합니다:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

다음 구성을 추가합니다:

```json theme={null}
{
  "mcpServers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

`uvx`를 사용하는 경우(사전 패키지 설치 필요 없음):

```json theme={null}
{
  "mcpServers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

구성을 저장한 후 Claude Desktop을 재시작하면 대화에서 Suno 관련 도구를 사용할 수 있습니다.

## VS Code / Cursor에서 사용하기

프로젝트 루트 디렉토리에 `.vscode/mcp.json`을 생성합니다:

```json theme={null}
{
  "servers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

또는 `uvx`를 사용할 수 있습니다:

```json theme={null}
{
  "servers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

## 사용 가능한 도구 목록

| 도구명                          | 설명                  |
| ---------------------------- | ------------------- |
| `suno_generate_music`        | 텍스트 프롬프트를 통해 음악 생성  |
| `suno_generate_custom_music` | 맞춤형 가사 및 스타일로 음악 생성 |
| `suno_extend_music`          | 지정된 시점에서 노래 이어쓰기    |
| `suno_cover_music`           | 커버 버전 생성            |
| `suno_concat_music`          | 노래 조각 연결            |
| `suno_generate_with_persona` | 지정된 음성 역할로 음악 생성    |
| `suno_remaster_music`        | 리마스터링               |
| `suno_stems_music`           | 트랙 분리(보컬/반주)        |
| `suno_replace_section`       | 노래의 특정 조각 교체        |
| `suno_upload_extend`         | 오디오 업로드 및 이어쓰기      |
| `suno_upload_cover`          | 오디오 업로드 및 커버        |
| `suno_mashup_music`          | 여러 곡 혼합             |
| `suno_generate_lyrics`       | 설명에 따라 가사 생성        |
| `suno_create_persona`        | 음성 역할 생성            |
| `suno_get_mp4`               | 노래 MP4 비디오 획득       |
| `suno_get_timing`            | 가사 타임라인 획득          |
| `suno_extract_vocals`        | 보컬 추출               |
| `suno_get_wav`               | 고품질 WAV 획득          |
| `suno_get_midi`              | MIDI 파일 획득          |
| `suno_optimize_style`        | 음악 스타일 태그 최적화       |
| `suno_mashup_lyrics`         | 가사 혼합               |
| `suno_upload_audio`          | 맞춤형 오디오 업로드         |
| `suno_get_task`              | 단일 작업 상태 조회         |
| `suno_get_tasks_batch`       | 배치 작업 상태 조회         |

## 사용 예시

구성이 완료되면 AI 클라이언트에서 자연어로 이러한 기능을 직접 호출할 수 있습니다, 예를 들어:

* 「여름에 관한 팝 음악을 생성해줘」
* 「이 노래를 재즈 스타일로 커버해줘」
* 「이 노래를 30초부터 이어 써줘」
* 「여행을 주제로 한 중국어 가사를 생성해줘」
* 「이 노래의 보컬을 분리해줘」
* 「이 노래를 MIDI 형식으로 변환해줘」

## 추가 정보

* GitHub 저장소: [XHuoAPI/SunoMCP](https://github.com/XHuoAPI/SunoMCP)
* PyPI 패키지: [mcp-suno](https://pypi.org/project/mcp-suno/)
* API 문서: [Suno 음악 생성 API](https://api.xhuoapi.ai/documents/suno)