mcp-kokoro-tts

Локальный MCP-сервер для синтеза речи на базе Kokoro-82M. Когда ваш агент вызывает speak, сервер синтезирует речь и воспроизводит её на вашем компьютере, чтобы вы могли слышать, как говорит обвязка.

Работает с любым MCP-клиентом: Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline и другими. Один короткий блок конфигурации, никаких API-ключей — синтез выполняется локально на основе Kokoro-82M.

При первом запуске сервер подготавливает два компонента, которых нет на PyPI: веса Kokoro-82M (~312 MB) — в локальный кэш, а английскую модель spaCy (en_core_web_sm) — в то же окружение Python, в котором запущен сервер. Второй компонент обязателен, потому что G2P-конвейер Kokoro загружает 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 — идентификатор голоса или абсолютный путь к .pt

2. Файл в каталоге voices/ пакета, имя которого начинается с default

3. Первый файл .pt в voices/ (в алфавитном порядке)

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 (API-токен PyPI). На проекте PyPI можно также включить GitHub trusted publishing; в этом workflow аутентификация выполняется с помощью токена, поэтому первый релиз не зависит от сопоставления с отложенным издателем.

Релиз

1. Поднимите version в pyproject.toml (и в 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 с PYPI_TOKEN

   • 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