> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/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)을 함께 확인해 주세요.
</Note>

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 키를 환경 변수로 전달해 실행합니다. 아래에서 클라이언트를 선택하세요.

<Tabs>
  <Tab title="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" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="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`                     |
  </Tab>

  <Tab title="Claude Code">
    터미널에서 한 줄로:

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

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

  <Tab title="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** 모드에서 사용하세요.
  </Tab>

  <Tab title="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 패널에서 서버 목록을 새로고침하세요.
  </Tab>
</Tabs>

## 환경 변수

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

## 도구

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

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

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

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

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

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

### 주요 `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` 그대로 병합이 동작합니다.

## 워크플로 예시

<CardGroup cols={1}>
  <Card title="검색 → 미리듣기 → 추정 → 합성" icon="wand-magic-sparkles">
    *"차분한 한국어 여성 보이스를 찾아서 샘플을 들려주고, 비용을 확인한 뒤, 이 공지를 mp3로 만들어줘."*

    `search_voice()` → `preview_voice()` → `predict_duration()` + `get_credit_balance()` → `text_to_speech()`로 연결됩니다.
  </Card>

  <Card title="복제 후 즉시 사용" icon="clone">
    *"\~/recordings/sample.wav로 MyVoice라는 복제 보이스를 만들고, 그 보이스로 이 인사말을 읽어서 재생해줘."*

    `clone_voice()` → `get_custom_voice()` → `text_to_speech(autoplay=true)`로 연결됩니다.
  </Card>

  <Card title="스크립트를 나눠 합성하고 이어붙이기" icon="layer-group">
    *"이 스크립트의 문단을 각각 합성한 뒤, 사이에 짧은 정적을 두고 하나의 mp3로 합쳐줘."*

    문단별 `text_to_speech()` → `merge_audio_files(gap_ms=...)`로 연결됩니다.
  </Card>
</CardGroup>

## 문제 해결

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

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

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

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

## 관련 문서

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/ko/docs/developer-tools/cli">
    동일한 기능을 터미널과 스크립트에서.
  </Card>

  <Card title="커스텀 보이스" icon="clone" href="/ko/docs/core-concepts/custom-voices">
    Supertone에서 보이스 복제가 작동하는 방식.
  </Card>
</CardGroup>