mcp-kokoro-tts

mcp-kokoro-tts

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

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

初回起動時に、サーバーは PyPI で配布されていないものを 2 つ用意します。Kokoro-82M の重み（約 312 MB）をローカルキャッシュにダウンロードし、spaCy の英語モデル（en_core_web_sm）をサーバーの実行環境と同じ Python 環境にインストールします。Kokoro の G2P パイプラインは spaCy を読み込むため、2 つ目のインストールが必要です。このパッケージがインストールしない限り、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

エージェントに呼び出させる

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 Hub のキャッシュディレクトリを上書きします
TTS_OUTPUT_DIR	生成した WAV ファイルの保存先ディレクトリ
TTS_PLAY	0 に設定すると、ローカル再生せずに音声を合成します
HF_TOKEN	ダウンロードを高速化する任意の Hugging Face トークン

プラットフォーム

OS	音声合成	再生
macOS	はい	afplay
Linux	はい	ffplay、paplay、または aplay
Windows	はい	PowerShell の MediaPlayer

espeak-ng は任意です。英語はインストールしなくても動作します。語彙外の単語への対応範囲を広げ、一部の英語以外の言語に対応するにはインストールしてください。

公開

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

PyPI への公開には、リポジトリシークレット PYPI_TOKEN（PyPI API トークン）を使用します。PyPI プロジェクトで GitHub の Trusted Publishing を設定することもできます。このワークフローはトークンで認証するため、初回リリースで保留中のパブリッシャーとの照合に依存しません。

リリース

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 ライセンスに基づき、別途ダウンロードされます。