> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Model Context Protocol로 Claude, Cursor, Claude Code, VS Code, Windsurf에 Supertone TTS를 연결하세요 — 설치, 도구, 문제 해결.

> [!NOTE]
>
> 이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/developer-tools/mcp)을 함께 확인해 주세요.

Supertone TTS를 Claude, Cursor 등 MCP 호환 클라이언트와 연동하세요. Supertone MCP 서버는 Text-to-Speech API를 조립 가능한 [Model Context Protocol](https://modelcontextprotocol.io) 도구 집합으로 노출합니다. 따라서 AI 에이전트가 보이스를 검색하고, 샘플을 미리듣고, 비용을 추정하고, 보이스를 복제하고, 음성을 합성하며 — 이 단계들을 스스로 다단계 워크플로로 연결할 수 있습니다.

소스: [supertone-inc/supertone-mcp](https://github.com/supertone-inc/supertone-mcp).

## 무엇을 할 수 있나요

* **음성 합성** — 보이스·언어·속도·피치·감정 스타일을 제어합니다.
* **보이스 검색** — 언어·성별·연령·사용 사례·스타일로 찾고, 결정 전에 샘플을 미리듣습니다.
* **복제·관리** — 로컬 오디오 파일로 커스텀 보이스를 만들고 관리합니다.
* **사용량 추적** — 크레딧 잔액과 사용 이력을 확인합니다.
* **오디오 이어붙이기** — 여러 클립을 하나의 파일로 병합합니다(무음 간격·크로스페이드 옵션).

## 사전 준비

* [`uv`](https://docs.astral.sh/uv/) 설치(`uvx` 제공), 또는 `pip`가 있는 Python.
* [Developer Console](https://console.supertoneapi.com)에서 발급한 Supertone API 키.

## 설치

모든 클라이언트는 동일한 서버(`uvx supertone-mcp`)를 API 키를 환경 변수로 전달해 실행합니다. 아래에서 클라이언트를 선택하세요.

**Cursor**

`~/.cursor/mcp.json`(전역) 또는 `.cursor/mcp.json`(프로젝트별)에 추가한 뒤 API 키를 입력하세요:

```json theme={"dark"}
{
  "mcpServers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
    }
  }
}
```

**Claude Desktop**

`claude_desktop_config.json`에 서버를 추가한 뒤 Claude Desktop을 재시작하세요:

```json theme={"dark"}
{
  "mcpServers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
    }
  }
}
```

설정 파일 위치:

| OS | 경로 |
| - | - |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

**Claude Code**

터미널에서 한 줄로:

```bash theme={"dark"}
claude mcp add supertone-tts -e SUPERTONE_API_KEY=your-api-key-here -- uvx supertone-mcp
```

모든 프로젝트에서 쓰려면 `-s user`를 추가하세요.

**VS Code**

워크스페이스의 `.vscode/mcp.json`에 추가하세요(최상위 키가 `servers`인 점에 유의):

```json theme={"dark"}
{
  "servers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
    }
  }
}
```

이후 MCP 뷰에서 서버를 활성화하고 Copilot Chat의 **Agent** 모드에서 사용하세요.

**Windsurf**

`~/.codeium/windsurf/mcp_config.json`에 추가하세요:

```json theme={"dark"}
{
  "mcpServers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
    }
  }
}
```

Windsurf의 Cascade 패널에서 서버 목록을 새로고침하세요.

## 환경 변수

| 변수 | 필수 | 기본값 | 용도 |
| - | - | - | - |
| `SUPERTONE_API_KEY` | 예 | — | 인증 |
| `SUPERTONE_MCP_VOICE_ID` | 아니요 | Aiden (다국어) | `text_to_speech`의 기본 `voice_id` |
| `SUPERTONE_OUTPUT_DIR` | 아니요 | `~/supertone-tts-output/` | 생성된 오디오 파일 저장 위치 |

## 도구

서버는 에이전트가 연결해 사용할 수 있는 조립형 빌딩 블록으로 기능을 노출합니다.

> **음성 합성**
>
> | 도구 | 설명 |
> | - | - |
> | `text_to_speech` | 속도·피치·감정 스타일·출력 포맷을 제어해 오디오를 생성합니다. |
> | `predict_duration` | 생성 전에 합성 길이와 크레딧 비용을 추정합니다. |

> **보이스 검색**
>
> | 도구 | 설명 |
> | - | - |
> | `search_voice` | 언어·성별·연령·사용 사례·스타일로 프리셋 보이스를 필터링합니다. |
> | `get_voice` | 보이스의 전체 상세 정보를 가져옵니다. |
> | `preview_voice` | 보이스 평가용 샘플 오디오 URL을 가져옵니다. |

> **보이스 복제**
>
> | 도구 | 설명 |
> | - | - |
> | `clone_voice` | 로컬 WAV/MP3(≤ 3 MB)로부터 복제 보이스를 생성합니다. |
> | `search_custom_voice` | 복제한 보이스를 목록화·필터링합니다. |
> | `get_custom_voice` | 복제 보이스의 상세 정보를 가져옵니다. |
> | `edit_custom_voice` | 복제 보이스의 이름이나 설명을 수정합니다. |
> | `delete_custom_voice` | 복제 보이스를 영구 삭제합니다(되돌릴 수 없음). |

> **사용량 및 크레딧**
>
> | 도구 | 설명 |
> | - | - |
> | `get_credit_balance` | 남은 크레딧을 확인합니다. |
> | `get_usage_history` | 기간별 사용량을 조회합니다. |
> | `get_voice_usage` | 특정 보이스의 사용량 지표를 확인합니다. |

> **오디오 편집**
>
> | 도구 | 설명 |
> | - | - |
> | `merge_audio_files` | 로컬 오디오 파일 2개 이상을 하나로 병합합니다 — 단순 연결, 무음 간격(`gap_ms`), 크로스페이드(`crossfade_ms`). 여러 `text_to_speech` 출력을 이어붙일 때 유용합니다. |

### 주요 `text_to_speech` 파라미터

* `text`(필수), `voice_id`, `language`, `output_format`(`mp3` / `wav`)
* `model` — 예: `sona_speech_2_flash`, `sona_speech_1`
* `speed`(0.5–2.0), `pitch_shift`(−24 \~ +24 반음), `style`
* `output_mode`(`files` / `resources` / `both`), `autoplay`(기본 `false`), `streaming`(`sona_speech_1` 전용)

이들은 호출별 파라미터이므로, 에이전트는 매 호출 시 출력 모드·자동 재생·모델을 제어합니다.

### 주요 `merge_audio_files` 파라미터

* `input_paths`(필수) — 순서대로 나열한 로컬 오디오 파일 2개 이상. (1개만 주면 그대로 반환됩니다.)
* `gap_ms` — 클립 사이에 삽입할 무음 길이(밀리초).
* `crossfade_ms` — 클립 사이의 크로스페이드 길이(밀리초). **`gap_ms`와 상호 배타적입니다.**
* `output_format` — 출력 포맷 강제 지정. 기본값은 자동 감지입니다: 입력 확장자가 모두 같으면 그 확장자, 섞여 있으면 `mp3`. 샘플레이트나 채널 수가 서로 달라도 병합 전에 자동 정규화됩니다.

ffmpeg는 `imageio-ffmpeg`로 번들되어 있어, 시스템에 ffmpeg를 설치하지 않아도 `uvx supertone-mcp` 그대로 병합이 동작합니다.

## 워크플로 예시

> **검색 → 미리듣기 → 추정 → 합성**
>
> *"차분한 한국어 여성 보이스를 찾아서 샘플을 들려주고, 비용을 확인한 뒤, 이 공지를 mp3로 만들어줘."*
>
> `search_voice()` → `preview_voice()` → `predict_duration()` + `get_credit_balance()` → `text_to_speech()`로 연결됩니다.

> **복제 후 즉시 사용**
>
> *"\~/recordings/sample.wav로 MyVoice라는 복제 보이스를 만들고, 그 보이스로 이 인사말을 읽어서 재생해줘."*
>
> `clone_voice()` → `get_custom_voice()` → `text_to_speech(autoplay=true)`로 연결됩니다.

> **스크립트를 나눠 합성하고 이어붙이기**
>
> *"이 스크립트의 문단을 각각 합성한 뒤, 사이에 짧은 정적을 두고 하나의 mp3로 합쳐줘."*
>
> 문단별 `text_to_speech()` → `merge_audio_files(gap_ms=...)`로 연결됩니다.

## 문제 해결

> **클라이언트에 Supertone 도구가 안 보임**
>
> 설정 파일이 유효한 JSON인지, 클라이언트를 완전히 재시작했는지 확인하세요. 대부분의 클라이언트는 시작 시에만 MCP 서버를 로드합니다.

> **uvx: command not found**
>
> `uvx`를 제공하는 `uv`를 설치하세요: [uv 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/) 참고. 또는 `pip install supertone-mcp` 후 `command`를 `supertone-mcp`로 설정하세요.

> **인증 오류**
>
> `SUPERTONE_API_KEY`가 (셸이 아니라) 서버의 `env` 블록에 설정되어 있고 유효한지 확인하세요. 키는 [Developer Console](https://console.supertoneapi.com)에서 발급받습니다.

> **생성한 오디오는 어디에?**
>
> `output_mode: files`이면 오디오는 `SUPERTONE_OUTPUT_DIR`(기본 `~/supertone-tts-output/`)에 저장됩니다. 즉시 재생하려면 `autoplay: true`로 설정하세요.

## 관련 문서

> **[CLI](/ko/docs/developer-tools/cli)**
>
> 동일한 기능을 터미널과 스크립트에서.

> **[커스텀 보이스](/ko/docs/core-concepts/custom-voices)**
>
> Supertone에서 보이스 복제가 작동하는 방식.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.