Skip to main content
Glama

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: mac-say-mcp

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

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

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

도구

speak

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

매개변수

필수

설명

text

예

말할 텍스트 (최대 500자)

voice

아니요

음성 ID (예: af_heart) 또는 .pt 음성 파일의 절대 경로

speed

아니요

재생 속도 배수 (기본값 1.0)

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"
      }
    }
  }
}

환경 변수

변수

설명

TTS_VOICE

기본 음성 ID 또는 .pt 절대 경로

TTS_MODEL_DIR

모델 캐시 디렉터리 재정의

TTS_HF_CACHE_DIR

Hugging Face 허브 캐시 디렉터리 재정의

TTS_OUTPUT_DIR

생성된 WAV 파일용 디렉터리

TTS_PLAY

로컬 재생 없이 합성하려면 0으로 설정

HF_TOKEN

더 빠른 다운로드를 위한 선택적 Hugging Face 토큰

플랫폼

OS

합성

재생

macOS

예

afplay

Linux

예

ffplay, paplay 또는 aplay

Windows

예

PowerShell MediaPlayer

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 라이선스에 따라 별도로 다운로드됩니다.

Available Tools

2 tools
list_voicesList voicesA

List Kokoro voices available to the speak tool and the currently selected default voice. Resolution order: TTS_VOICE env var, voices/default* file, first file in voices/, then the model's default af_heart voice.

Inputs: no named parameters. Returns: result

speakSpeakA

Synthesize speech with Kokoro-82M and play it on the user's machine. Call this when the user wants the harness to talk, read something aloud, or hear a spoken response. Always pass clear, natural text to speak. Default voice resolution: TTS_VOICE env var, voices/default* in the package, first file in voices/, then the bundled af_heart voice from the model.

Inputs: text (required), speed, voice. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one performs speech synthesis ('speak'), the other lists available voices ('list_voices'). No ambiguity between them, as they serve complementary roles in the TTS workflow.

    Naming Consistency5/5

    Both tool names follow an imperative verb style ('speak', 'list_voices'), which is concise and predictable. 'list_voices' uses a verb_noun pattern, but the naming is consistent in tone and clarity for a small set.

    Tool Count5/5

    With only 2 tools, the server is minimal yet well-scoped for its purpose: a text-to-speech harness. The count is appropriate; additional tools would likely be redundant.

    Completeness4/5

    The core operation (speak) is present, and the companion list_voices provides necessary context for voice selection. Minor gaps exist, such as no pause/stop or voice configuration tool, but these are not critical for basic TTS functionality.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers