Skip to main content
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
Supertone TTS를 Claude, Cursor 등 MCP 호환 클라이언트와 연동하세요. Supertone MCP 서버는 Text-to-Speech API를 조립 가능한 Model Context Protocol 도구 집합으로 노출합니다. 따라서 AI 에이전트가 보이스를 검색하고, 샘플을 미리듣고, 비용을 추정하고, 보이스를 복제하고, 음성을 합성하며 — 이 단계들을 스스로 다단계 워크플로로 연결할 수 있습니다. 소스: supertone-inc/supertone-mcp.

​
무엇을 할 수 있나요

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

​
사전 준비

  • uv 설치(uvx 제공), 또는 pip가 있는 Python.
  • Developer Console에서 발급한 Supertone API 키.

​
설치

모든 클라이언트는 동일한 서버(uvx supertone-mcp)를 API 키를 환경 변수로 전달해 실행합니다. 아래에서 클라이언트를 선택하세요.
~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트별)에 추가한 뒤 API 키를 입력하세요:
{
  "mcpServers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
    }
  }
}

​
환경 변수

변수필수기본값용도
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=...)로 연결됩니다.

​
문제 해결

설정 파일이 유효한 JSON인지, 클라이언트를 완전히 재시작했는지 확인하세요. 대부분의 클라이언트는 시작 시에만 MCP 서버를 로드합니다.
uvx를 제공하는 uv를 설치하세요: uv 설치 가이드 참고. 또는 pip install supertone-mcp 후 command를 supertone-mcp로 설정하세요.
SUPERTONE_API_KEY가 (셸이 아니라) 서버의 env 블록에 설정되어 있고 유효한지 확인하세요. 키는 Developer Console에서 발급받습니다.
output_mode: files이면 오디오는 SUPERTONE_OUTPUT_DIR(기본 ~/supertone-tts-output/)에 저장됩니다. 즉시 재생하려면 autoplay: true로 설정하세요.

​
관련 문서

CLI

동일한 기능을 터미널과 스크립트에서.

커스텀 보이스

Supertone에서 보이스 복제가 작동하는 방식.