mcp-kokoro-tts
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-provisionRelated 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 파일을 작성한 후 로컬에서 재생합니다.
매개변수 | 필수 | 설명 |
| 예 | 말할 텍스트 (최대 500자) |
| 아니요 | 음성 ID (예: |
| 아니요 | 재생 속도 배수 (기본값 |
list_voices
사용 가능한 Kokoro 음성과 현재 선택된 기본 음성을 나열합니다.
음성 선택
선택 순서:
TTS_VOICE환경 변수 — 음성 ID 또는.pt절대 경로패키지
voices/폴더에서 이름이default로 시작하는 파일voices/의 첫 번째.pt파일 (알파벳순)모델에 포함된
af_heart음성
{
"mcpServers": {
"mcp-kokoro-tts": {
"command": "uvx",
"args": ["mcp-kokoro-tts"],
"env": {
"TTS_VOICE": "af_heart"
}
}
}
}환경 변수
변수 | 설명 |
| 기본 음성 ID 또는 |
| 모델 캐시 디렉터리 재정의 |
| Hugging Face 허브 캐시 디렉터리 재정의 |
| 생성된 WAV 파일용 디렉터리 |
| 로컬 재생 없이 합성하려면 |
| 더 빠른 다운로드를 위한 선택적 Hugging Face 토큰 |
플랫폼
OS | 합성 | 재생 |
macOS | 예 |
|
Linux | 예 |
|
Windows | 예 | PowerShell |
espeak-ng는 선택 사항입니다. 영어는 없어도 작동합니다. 어휘 외 단어 커버리지와 일부 비영어 언어를 위해 설치하세요.
배포
버전 태그를 지정하면 GitHub Actions publish.yml이 실행되어 PyPI에 업로드한 다음 MCP Registry에 업로드합니다.
PyPI 배포는 저장소 시크릿 PYPI_TOKEN(PyPI API 토큰)을 사용합니다. PyPI 프로젝트에 GitHub trusted publishing을 구성할 수도 있습니다. 이 워크플로는 토큰으로 인증하므로 첫 릴리스가 pending-publisher 매칭에 의존하지 않습니다.
릴리스
pyproject.toml의version을 올립니다 (아직 태그를 지정하지 않는 경우server.json도)커밋하고 태그 지정:
git tag v0.1.2 && git push origin v0.1.2GitHub 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 toolslist_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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Text-to-Speech
Hosted text-to-speech MCP server: 66 voices in 9 languages, long-form narration, podcasts.
Remote text-to-speech MCP server with text_to_speech and list_voices tools. Free plan.
AI voice generation: text-to-speech and voice cloning from any MCP client.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables users to convert text into high-quality audio by accessing the OpenAI Text-to-Speech API. It supports customizable model selection and voice options for synthesized speech generation via the MCP protocol.1MIT
- AlicenseAqualityDmaintenanceMCP server for text-to-speech using macOS say command, enabling speech synthesis, audio file generation, and voice management.51MIT

leanvox-mcpofficial
AlicenseNot gradedqualityDmaintenanceEnables text-to-speech generation, voice cloning, dialogue creation, and other TTS operations through natural language in MCP-compatible AI assistants.10 npmMIT- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to speak by running local voice models using Chatterbox Turbo TTS or Kokoro TTS, with support for voice cloning, paralinguistic tags, and multiple voices.89 npm13MIT