mcp-kokoro-tts

로컬 Kokoro-82M 텍스트 음성 변환 MCP 서버입니다. 에이전트가 speak를 호출하면 음성을 합성하여 사용자 컴퓨터에서 재생하므로 하네스가 말하는 소리를 들을 수 있습니다.

Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline 등 모든 MCP 클라이언트에서 작동합니다. 짧은 구성 블록 하나면 충분하며 API 키가 필요 없습니다. 합성은 Kokoro-82M으로 로컬에서 실행됩니다.

첫 시작 시 서버는 PyPI에 없는 두 가지를 준비합니다: Kokoro-82M 가중치(약 312MB)를 로컬 캐시에, 그리고 spaCy의 영어 모델(en_core_web_sm)을 서버가 실행 중인 동일한 Python 환경에 설치합니다. 두 번째 설치가 필요한 이유는 Kokoro의 G2P 파이프라인이 spaCy를 로드하기 때문이며, uvx/uv tool 환경에는 이 패키지가 설치하지 않는 한 모델이 없기 때문입니다.

설치

클라이언트의 MCP 구성에 추가하세요:

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"]
    }
  }
}

Python 3.12와 uv가 필요합니다. 첫 서버 시작 시 Kokoro 가중치와 spaCy 영어 모델이 자동으로 준비됩니다.

MCP 서버를 시작하지 않고 둘 다 미리 다운로드하려면:

uvx mcp-kokoro-tts-provision

Related MCP server: MCP TTS Server

에이전트가 호출하도록 만들기

AGENTS.md / CLAUDE.md / 시스템 프롬프트에 한 줄을 추가하세요:

When the user wants to hear something spoken aloud, call the `speak` tool with clear, natural text.

도구

speak

음성을 합성하고 WAV 파일을 작성한 후 로컬에서 재생합니다.

list_voices

사용 가능한 Kokoro 음성과 현재 선택된 기본 음성을 나열합니다.

음성 선택

선택 순서:

1. TTS_VOICE 환경 변수 — 음성 ID 또는 .pt 절대 경로

2. 패키지 voices/ 폴더에서 이름이 default로 시작하는 파일

3. voices/의 첫 번째 .pt 파일 (알파벳순)

4. 모델에 포함된 af_heart 음성

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"],
      "env": {
        "TTS_VOICE": "af_heart"
      }
    }
  }
}

환경 변수

플랫폼

espeak-ng는 선택 사항입니다. 영어는 없어도 작동합니다. 어휘 외 단어 커버리지와 일부 비영어 언어를 위해 설치하세요.

배포

버전 태그를 지정하면 GitHub Actions publish.yml이 실행되어 PyPI에 업로드한 다음 MCP Registry에 업로드합니다.

PyPI 배포는 저장소 시크릿 PYPI_TOKEN(PyPI API 토큰)을 사용합니다. PyPI 프로젝트에 GitHub trusted publishing을 구성할 수도 있습니다. 이 워크플로는 토큰으로 인증하므로 첫 릴리스가 pending-publisher 매칭에 의존하지 않습니다.

릴리스

1. pyproject.toml의 version을 올립니다 (아직 태그를 지정하지 않는 경우 server.json도)

2. 커밋하고 태그 지정: git tag v0.1.2 && git push origin v0.1.2

3. GitHub Actions가 publish.yml을 실행합니다:

   • release — 타입체크, 테스트, wheel/sdist 빌드

   • pypi-publish — PYPI_TOKEN으로 PyPI에 업로드

   • mcp-registry — OIDC → MCP Registry (PyPI 성공 후)

개발

cd mcps-tts
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pyright
pytest
python -m mcp_kokoro_tts

라이선스

Apache-2.0. LICENSE 및 NOTICE를 참조하세요. Kokoro-82M 모델 가중치는 Apache-2.0 라이선스에 따라 별도로 다운로드됩니다.