mcp-kokoro-tts

Servidor MCP de texto a voz Kokoro-82M local. Cuando tu agente llama a speak, sintetiza el habla y la reproduce en tu máquina para que puedas oír hablar al harness.

Funciona con cualquier cliente MCP: Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline y más. Un bloque de configuración corto, sin claves API: la síntesis se ejecuta localmente con Kokoro-82M.

En el primer inicio, el servidor aprovisiona dos cosas que no están en PyPI: los pesos de Kokoro-82M (~312 MB) en una caché local, y el modelo de inglés de spaCy (en_core_web_sm) en el mismo entorno de Python en el que se ejecuta el servidor. Esa segunda instalación es necesaria porque el pipeline G2P de Kokoro carga spaCy, y un entorno uvx / uv tool no tendrá el modelo a menos que este paquete lo coloque allí.

Instalación

Añade a la configuración MCP de tu cliente:

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

Requiere Python 3.12 y uv. El primer inicio del servidor aprovisiona los pesos de Kokoro y el modelo de inglés de spaCy automáticamente.

Para descargar ambos previamente sin iniciar el servidor MCP:

uvx mcp-kokoro-tts-provision

Related MCP server: MCP TTS Server

Haz que el agente lo llame

Añade una línea a tu AGENTS.md / CLAUDE.md / prompt del sistema:

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

Herramientas

speak

Sintetiza el habla, escribe un archivo WAV y lo reproduce localmente.

list_voices

Lista las voces Kokoro disponibles y la predeterminada seleccionada actualmente.

Elegir tu voz

Orden de resolución:

1. Variable de entorno TTS_VOICE — identificador de voz o ruta absoluta .pt

2. Un archivo en la carpeta voices/ del paquete cuyo nombre comience con default

3. Primer archivo .pt en voices/ (alfabético)

4. La voz af_heart incluida en el modelo

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

Variables de entorno

Plataformas

espeak-ng es opcional. El inglés funciona sin él; instálalo para una mejor cobertura de palabras fuera de vocabulario y algunos idiomas no ingleses.

Publicación

Etiquetar una versión ejecuta publish.yml de GitHub Actions, que sube a PyPI y luego al Registro MCP.

La publicación en PyPI usa el secreto del repositorio PYPI_TOKEN (un token de API de PyPI). La publicación confiable de GitHub también se puede configurar en el proyecto de PyPI; este flujo de trabajo se autentica con el token para que un primer lanzamiento no dependa de la coincidencia de publicador pendiente.

Lanzamiento

1. Incrementa version en pyproject.toml (y server.json si aún no estás etiquetando)

2. Confirma y etiqueta: git tag v0.1.2 && git push origin v0.1.2

3. GitHub Actions ejecuta publish.yml:

   • release — verificación de tipos, pruebas, compilación de wheel/sdist

   • pypi-publish — subir a PyPI con PYPI_TOKEN

   • mcp-registry — OIDC → Registro MCP (después de que PyPI tenga éxito)

Desarrollo

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

Licencia

Apache-2.0. Consulta LICENSE y NOTICE. Los pesos del modelo Kokoro-82M se descargan por separado bajo su licencia Apache-2.0.