Skip to main content
Glama

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

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.

Parámetro

Requerido

Descripción

text

sí

Texto a hablar (máx. 500 caracteres)

voice

no

Identificador de voz (p. ej. af_heart) o ruta absoluta a un archivo de voz .pt

speed

no

Multiplicador de velocidad de reproducción (por defecto 1.0)

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

Variable

Descripción

TTS_VOICE

Identificador de voz predeterminado o ruta absoluta .pt

TTS_MODEL_DIR

Anula el directorio de caché del modelo

TTS_HF_CACHE_DIR

Anula el directorio de caché del hub de Hugging Face

TTS_OUTPUT_DIR

Directorio para los archivos WAV generados

TTS_PLAY

Establecer a 0 para sintetizar sin reproducción local

HF_TOKEN

Token opcional de Hugging Face para descargas más rápidas

Plataformas

SO

Síntesis

Reproducción

macOS

sí

afplay

Linux

sí

ffplay, paplay o aplay

Windows

sí

PowerShell MediaPlayer

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.

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