Skip to main content
Glama

mcp-kokoro-tts

ローカルKokoro-82Mテキスト読み上げMCPサーバーです。エージェントがspeakを呼び出すと、音声を合成してあなたのマシンで再生するため、ハーネスが話すのを聞くことができます。

あらゆるMCPクライアントで動作します:Claude Desktop、Claude Code、Cursor、VS Code、opencode、Clineなど。短い設定ブロックを1つ追加するだけで、APIキーは不要です。音声合成はKokoro-82Mでローカルに実行されます。

初回起動時に、サーバーはPyPIにない2つのものを用意します: Kokoro-82Mの重みデータ(約312 MB)をローカルキャッシュへ、spaCyの英語モデル(en_core_web_sm)をサーバーが実行しているのと同じPython環境へ。この2つ目のインストールが必要なのは、KokoroのG2Pパイプラインが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 / システムプロンプトに1行追加します:

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

ツール

speak

音声を合成し、WAVファイルを書き出して、ローカルで再生します。

パラメータ

必須

説明

text

はい

読み上げるテキスト(最大500文字)

voice

いいえ

音声ID(例:af_heart)または.pt音声ファイルの絶対パス

speed

いいえ

再生速度の倍率(デフォルト 1.0)

list_voices

利用可能なKokoroの音声と、現在選択されているデフォルトを一覧表示します。

音声の選択

解決順:

  1. TTS_VOICE 環境変数 — 音声IDまたは絶対パスの.ptパス

  2. パッケージのvoices/フォルダ内で名前がdefaultで始まるファイル

  3. voices/内の最初の.ptファイル(アルファベット順)

  4. モデルに同梱のaf_heart音声

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

環境変数

変数

説明

TTS_VOICE

デフォルトの音声IDまたは絶対パスの.ptパス

TTS_MODEL_DIR

モデルキャッシュディレクトリを上書き

TTS_HF_CACHE_DIR

Hugging Faceハブのキャッシュディレクトリを上書き

TTS_OUTPUT_DIR

生成されたWAVファイルのディレクトリ

TTS_PLAY

0に設定すると、ローカル再生なしで合成

HF_TOKEN

ダウンロードを高速化するためのオプションのHugging Faceトークン

プラットフォーム

OS

合成

再生

macOS

対応

afplay

Linux

対応

ffplay、paplay、またはaplay

Windows

対応

PowerShell MediaPlayer

espeak-ngはオプションです。英語はこれなしで動作します。語彙外(out-of-vocabulary)のカバレッジを向上させ、一部の非英語言語を扱うにはインストールしてください。

公開

バージョンにタグを付けるとGitHub Actionsのpublish.ymlが実行され、PyPIにアップロードした後、MCP Registryにアップロードします。

PyPIへの公開には、リポジトリのシークレットPYPI_TOKEN(PyPI APIトークン)を使用します。GitHubのtrusted publishingはPyPIプロジェクト側でも設定できます。このワークフローはトークンで認証するため、初回リリースはpending-publisherのマッチングに依存しません。

リリース

  1. pyproject.tomlのversionを上げます(まだタグを付けない場合は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_TOKENでPyPIにアップロード

    • 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.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