Skip to main content
Glama

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: 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

нет

Идентификатор голоса (например, af_heart) или абсолютный путь к голосовому файлу .pt

speed

нет

Множитель скорости воспроизведения (по умолчанию 1.0)

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

Переменные окружения

Переменная

Описание

TTS_VOICE

Идентификатор голоса по умолчанию или абсолютный путь к .pt

TTS_MODEL_DIR

Переопределяет каталог кэша моделей

TTS_HF_CACHE_DIR

Переопределяет каталог кэша Hugging Face Hub

TTS_OUTPUT_DIR

Каталог для создаваемых WAV-файлов

TTS_PLAY

Установите 0, чтобы синтезировать без локального воспроизведения

HF_TOKEN

Необязательный токен Hugging Face для более быстрой загрузки

Платформы

ОС

Синтез

Воспроизведение

macOS

да

afplay

Linux

да

ffplay, paplay или aplay

Windows

да

PowerShell MediaPlayer

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

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