Skip to main content
Glama

mcp-kokoro-tts

Lokaler Kokoro-82M-Text-to-Speech-MCP-Server. Wenn Ihr Agent speak aufruft, synthetisiert er Sprache und spielt sie auf Ihrem Rechner ab, sodass Sie den Harness sprechen hören können.

Funktioniert mit jedem MCP-Client: Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline und mehr. Ein kurzer Konfigurationsblock, keine API-Schlüssel – die Synthese läuft lokal mit Kokoro-82M.

Beim ersten Start stellt der Server zwei Dinge bereit, die nicht auf PyPI sind: die Kokoro-82M-Gewichte (~312 MB) in einen lokalen Cache und das englische spaCy-Modell (en_core_web_sm) in dieselbe Python-Umgebung, in der der Server läuft. Diese zweite Installation ist erforderlich, da Kokoros G2P-Pipeline spaCy lädt und eine uvx-/uv tool-Umgebung das Modell nicht enthält, es sei denn, dieses Paket legt es dort ab.

Installation

Fügen Sie Folgendes zur MCP-Konfiguration Ihres Clients hinzu:

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

Erfordert Python 3.12 und uv. Der erste Serverstart stellt Kokoro-Gewichte und das englische spaCy-Modell automatisch bereit.

Um beide vorab herunterzuladen, ohne den MCP-Server zu starten:

uvx mcp-kokoro-tts-provision

Related MCP server: mac-say-mcp

Den Agenten dazu bringen, es aufzurufen

Fügen Sie eine Zeile zu Ihrer AGENTS.md / CLAUDE.md / Systemaufforderung hinzu:

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

Werkzeuge

speak

Synthetisiert Sprache, schreibt eine WAV-Datei und spielt sie lokal ab.

Param

Erforderlich

Beschreibung

text

ja

Zu sprechender Text (max. 500 Zeichen)

voice

nein

Stimm-ID (z. B. af_heart) oder absoluter Pfad zu einer .pt-Stimmdatei

speed

nein

Wiedergabegeschwindigkeits-Multiplikator (Standard 1.0)

list_voices

Listet verfügbare Kokoro-Stimmen und die aktuell ausgewählte Standardstimme auf.

Auswahl Ihrer Stimme

Auflösungsreihenfolge:

  1. TTS_VOICE-Umgebungsvariable – Stimm-ID oder absoluter .pt-Pfad

  2. Eine Datei im voices/-Ordner des Pakets, deren Name mit default beginnt

  3. Erste .pt-Datei in voices/ (alphabetisch)

  4. Die gebündelte af_heart-Stimme des Modells

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

Umgebungsvariablen

Variable

Beschreibung

TTS_VOICE

Standard-Stimm-ID oder absoluter .pt-Pfad

TTS_MODEL_DIR

Modell-Cache-Verzeichnis überschreiben

TTS_HF_CACHE_DIR

Hugging-Face-Hub-Cache-Verzeichnis überschreiben

TTS_OUTPUT_DIR

Verzeichnis für generierte WAV-Dateien

TTS_PLAY

Auf 0 setzen, um ohne lokale Wiedergabe zu synthetisieren

HF_TOKEN

Optionales Hugging-Face-Token für schnellere Downloads

Plattformen

OS

Synthese

Wiedergabe

macOS

ja

afplay

Linux

ja

ffplay, paplay oder aplay

Windows

ja

PowerShell MediaPlayer

espeak-ng ist optional. Englisch funktioniert ohne es; installieren Sie es für eine bessere Abdeckung von Wörtern außerhalb des Vokabulars und einige nicht-englische Sprachen.

Veröffentlichung

Das Taggen einer Version führt GitHub Actions publish.yml aus, das zuerst auf PyPI und dann in die MCP-Registry hochlädt.

Die Veröffentlichung auf PyPI verwendet das Repo-Geheimnis PYPI_TOKEN (ein PyPI-API-Token). GitHub Trusted Publishing kann auch auf dem PyPI-Projekt konfiguriert werden; dieser Workflow authentifiziert sich mit dem Token, sodass eine erste Veröffentlichung nicht von der Übereinstimmung mit einem ausstehenden Publisher abhängt.

Release

  1. version in pyproject.toml erhöhen (und server.json, falls Sie noch nicht taggen)

  2. Committen und taggen: git tag v0.1.2 && git push origin v0.1.2

  3. GitHub Actions führt publish.yml aus:

    • release – Typprüfung, Tests, Wheel/sdist bauen

    • pypi-publish – Upload zu PyPI mit PYPI_TOKEN

    • mcp-registry – OIDC → MCP-Registry (nach erfolgreichem PyPI-Upload)

Entwicklung

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

Lizenz

Apache-2.0. Siehe LICENSE und NOTICE. Die Kokoro-82M-Modellgewichte werden separat unter ihrer Apache-2.0-Lizenz heruntergeladen.

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