텍스트 음성 변환 MCP 서버: AI 에이전트가 소리 내어 말하게

설치

Python 3.10 이상이 필요합니다. MCP Python SDK와 엔진을 설치하세요:

pip install mcp superclonica-cpu

엔진은 처음 실행할 때 Supertonic 3 모델(약 400 MB)을 내려받고, 그다음부터는 일반 CPU에서 오프라인으로 돌아갑니다. Linux에서는 alsa-utils의 aplay로 소리를 재생하고, Windows와 macOS는 따로 필요한 것이 없습니다.

서버

이 파일을 tts_mcp.py로 저장하세요. speak 도구 하나를 등록해 텍스트를 음성으로 바꾸고 스피커로 재생한 뒤 에이전트에게 완료를 알립니다:

import os, subprocess, sys, tempfile
from mcp.server.mcpserver import MCPServer
from superclonica import Superclonica

VOICE = os.environ.get("TTS_VOICE", "F1")  # M1..M5, F1..F5 or a voice file from the catalog
server = MCPServer("speak")
tts = None

def play(path):
    if sys.platform == "win32":
        import winsound
        winsound.PlaySound(path, winsound.SND_FILENAME)
    elif sys.platform == "darwin":
        subprocess.run(["afplay", path], check=True)
    else:
        subprocess.run(["aplay", "-q", path], check=True)

@server.tool()
def speak(text: str, language: str = "en") -> str:
    """Say a short message out loud to the user, for example when a long task is done."""
    global tts
    tts = tts or Superclonica()
    audio, _ = tts.synthesize(text[:500], voice=VOICE, lang=language)
    path = os.path.join(tempfile.gettempdir(), "mcp-speak.wav")
    tts.save(path, audio)
    play(path)
    return "spoken"

if __name__ == "__main__":
    server.run()

모델은 첫 호출 때 로드되므로 에이전트는 빨리 시작하고, 첫 문장만 몇 초 더 걸립니다. 코드는 mcp 패키지 버전 2용이며 FastMCP가 MCPServer로 이름이 바뀌었습니다. 버전 1에서는 mcp.server.fastmcp에서 FastMCP를 가져오세요. 에이전트는 docstring을 보고 도구를 언제 부를지 정하므로, 원하는 사용 상황을 그곳에 적으세요.

Claude Code, Claude Desktop, Cursor에 연결하기

Claude Code에서는 명령 하나로 서버를 추가합니다:

claude mcp add speak -- python /full/path/to/tts_mcp.py

Claude Desktop에서는 claude_desktop_config.json에 추가하고, Cursor도 같은 mcpServers 블록을 mcp.json에서 읽습니다. 패키지를 설치한 Python의 전체 경로를 쓰세요:

{
  "mcpServers": {
    "speak": {
      "command": "/full/path/to/python",
      "args": ["/full/path/to/tts_mcp.py"],
      "env": {"TTS_VOICE": "F1"}
    }
  }
}

그다음 프로젝트 지침 등에 "작업을 마치거나 내 입력이 필요하면 짧은 한 문장으로 speak를 호출해"처럼 말할 때를 알려 주세요.

API로 같은 도구 만들기

400 MB 모델을 두고 싶지 않은 노트북에서는 SuperClonica 음성 합성 API로 읽으세요. speak의 합성 두 줄을 이 함수 호출로 바꾸고 SUPERCLONICA_KEY와 VOICE_ID를 설정합니다.

import os, requests

API = "https://superclonica.com/api/v1/speech"
VOICE_ID = os.environ["VOICE_ID"]  # the ID on the page of a catalog voice

def voice_to_file(text, language, path):
    answer = requests.post(API, timeout=120,
                           headers={"Authorization": "Bearer " + os.environ["SUPERCLONICA_KEY"]},
                           json={"text": text, "voice": VOICE_ID, "language": language, "format": "wav"})
    answer.raise_for_status()
    with open(path, "wb") as file:
        file.write(answer.content)

카탈로그의 모든 목소리는 어떤 요금제에서든 페이지에 표시된 ID로 쓸 수 있습니다. 무료 키는 하루 1분으로, 한 문장짜리 상태 알림에는 충분합니다.

목소리 고르기

TTS_VOICE에는 기본 목소리 10개(M1~M5, F1~F5) 중 하나나 SuperClonica 카탈로그의 목소리 파일 경로를 넣습니다. 차분한 내레이터, 우주선 컴퓨터, 게임 캐릭터 등입니다. 무료 목소리는 계정 없이 내려받을 수 있습니다. 먼저 목소리 페이지에서 들어 보고 테스트 문장을 변환해 보세요.