Local Voice Mcp

Local Voice MCP

Chatterbox Turbo TTS または Kokoro TTS を使用してローカル音声モデルを実行し、MCP クライアントが音声を再生できるようにします。

クイックスタート

このパッケージには、高品質な女性のリファレンス音声が含まれており、Chatterbox Turbo TTS のデフォルトで使用されます。環境変数はすべて任意です。

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "USE_MALE_VOICE": "false",
        "CHATTERBOX_MAX_CHARACTERS": "2000",
        "CHATTERBOX_PLAYBACK_VOLUME": "75"
      }
    }
  }
}

TTS エンジンの選択

Local Voice MCP は、2 つの TTS エンジンに対応しています。

Chatterbox Turbo TTS（デフォルト）

音声クローニングとパラ言語タグに対応した、高品質な音声合成です。ハードウェアに最適なバックエンドを自動的に検出して使用します。

• ✅ クロスプラットフォーム対応（macOS、Windows、Linux）
• ✅ リファレンス音声を使った音声クローニング
• ✅ 表情豊かな音声のためのパラ言語タグ（[laugh]、[sigh]、[cough] など）
• ✅ 複数アーキテクチャの自動検出：
  • Apple Silicon（MPS）：mlx-community/chatterbox-turbo-6bit で MLX を使用
  • NVIDIA GPU（CUDA）：ChatterboxTurboTTS で PyTorch を使用
  • CPU：PyTorch によるフォールバック
• ✅ モデルが小型（3億5,000万パラメーター）で、レイテンシーが低い

Kokoro TTS（クロスプラットフォーム）

マルチリンガルおよび複数音声に対応した、ONNX ランタイムを使用する高品質なオープンソース TTS です。

• ✅ クロスプラットフォーム（macOS、Windows、Linux）
• ✅ 複数の言語（en-us、en-gb、fr-fr、it、ja、cmn）
• ✅ 性別やアクセントを選べる40種類以上の音声
• ✅ 音声ブレンド機能
• ✅ 調整可能な読み上げ速度
• ✅ GPU 対応
• ✅ 長文コンテンツに対応（長さの制限なし）
• ✅ 依存関係とモデルを自動でインストール（手動でのインストールは不要です！）

Kokoro を使用するには、TTS_ENGINE 環境変数を設定します。

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "TTS_ENGINE": "kokoro",
        "KOKORO_LANGUAGE": "en-us",
        "KOKORO_VOICE": "af_sarah",
        "KOKORO_SPEED": "1.0"
      }
    }
  }
}

セットアップ：

Kokoro TTS は、初回使用時に Python の依存関係を自動でインストールし、モデルファイル（約100MB）をダウンロードします。MCP サーバーを設定するだけで、すぐに使用できます。

初回使用時の動作：

• Python パッケージ（kokoro-onnx、soundfile、numpy）が pip 経由で自動インストールされます
• モデルファイル（kokoro-v1.0.onnx 約90MB、voices-v1.0.bin 約13MB）が自動でダウンロードされます
• ファイルは今後の使用に備えて ~/.cache/kokoro-tts/ にキャッシュされます
• この初回セットアップには、インターネット接続環境に応じて約1～2分かかります

手動インストール（任意）：

依存関係を手動でインストールする場合や、自動インストールに失敗する場合は、以下の手順に従ってください。

# Install Python dependencies
pip install kokoro-onnx soundfile numpy

# Model files will still auto-download, or you can download manually:
cd ~/.cache/kokoro-tts
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

利用可能な音声：

• 🇺🇸 アメリカ英語：af_alloy、af_bella、af_sarah、af_nova、am_adam、am_michael、am_eric など
• 🇬🇧 イギリス英語：bf_emma、bf_isabella、bm_george、bm_lewis など
• 🇫🇷 フランス語：ff_siwis
• 🇮🇹 イタリア語：if_sara、im_nicola
• 🇯🇵 日本語：jf_alpha、jm_kumo など
• 🇨🇳 中国語：zf_xiaobei、zm_yunjian など

音声ブレンド： Kokoro は複数の音声をブレンドして、独自の音声特性を作り出せます。

# 60-40 mix of two voices
KOKORO_VOICE="af_sarah:60,am_adam:40"

# Equal blend (50-50)
KOKORO_VOICE="am_adam,af_sarah"

機能

• MCP サーバーの実装：@modelcontextprotocol/sdk を使用した、完全な Model Context Protocol サーバー
• HTTP API：直接統合できる ElevenLabs 互換の REST API
• テキスト読み上げ合成：Chatterbox Turbo TTS による高品質な音声合成
• 音声クローニング：音声クローニング用のリファレンス音声に対応
• パラ言語タグ：テキストに [laugh]、[sigh]、[cough] などの表現要素を直接追加
• 複数アーキテクチャ対応：最適なバックエンドを自動検出して使用（Apple Silicon では MLX、NVIDIA では CUDA、CPU ではフォールバック）
• 音量コントロール：クロスプラットフォームに対応した、設定可能な音声再生音量
• 堅牢なファイル管理：一時音声ファイルを自動クリーンアップ
• セキュリティ：ディレクトリトラバーサルを防止するパスの検証とサニタイズ
• デュアルモード動作：MCP サーバーまたは HTTP サーバーとして実行

インストール

npm から（推奨）

npm install -g local-voice-mcp

ソースから

git clone <repository-url>
cd local-voice-mcp
npm install
npm run build

使用方法

MCP サーバーモード（デフォルト）

stdio トランスポートを使用して MCP サーバーとして実行します。

local-voice-mcp-server

または、npx を使用します。

npx local-voice-mcp-server

HTTP サーバーモード

HTTP サーバーとして実行します。

MCP_MODE=http local-voice-mcp-server

または、ポートを設定します。

PORT=3000 MCP_MODE=http local-voice-mcp-server

開発

# Run MCP server in development
npm run dev:mcp

# Run HTTP server in development
npm run dev:http

# Run tests
npm test

# Build project
npm run build

MCP ツール

MCP モードで実行すると、以下のツールを利用できます。

synthesize_text

設定された TTS エンジンを使用してテキストを音声に変換し、音声データを返します。

共通パラメーター：

• text（string、必須）：合成するテキスト

Chatterbox Turbo 固有のパラメーター：

• referenceAudio（string、任意）：ボイスクローン用の参照音声のパス

注意： Chatterbox Turbo では、韻律パラメーターの代わりにテキスト内で直接、パラ言語タグを使用します。表現豊かな音声にするには、テキストに [laugh]、[sigh]、[cough]、[chuckle]、[gasp]、[groan]、[clear throat]、[sniff]、[shush] などのタグを含めてください。

Kokoro 固有のパラメーター：

• speed（number、任意）：音声の速度（0.5～2.0、デフォルト：1.0）
• language（string、任意）：言語コード（例：'en-us'、'en-gb'、'fr-fr'、'ja'、'cmn'、デフォルト：'en-us'）
• voice（string、任意）：音声名（例：'af_sarah'、'am_adam'、'bf_emma'、デフォルト：'af_sarah'）
• model_path（string、任意）：Kokoro ONNX モデルファイルのパス
• voices_path（string、任意）：Kokoro voices bin ファイルのパス

戻り値：

• 合成ステータスとファイルパスを含む JSON レスポンス

レスポンス例：

{
  "success": true,
  "message": "Speech synthesis completed successfully",
  "audioFile": "/tmp/local-voice-mcp/audio_20240115_103000_abc123.wav",
  "textLength": 25,
  "audioFormat": "wav",
  "engine": "chatterbox",
  "engineName": "chatterbox",
  "options": {},
  "generatedAt": "2024-01-15T10:30:00.000Z"
}

音声ファイルは一時ディレクトリに保存され、任意のオーディオプレーヤーで再生するか、プログラムからアクセスできます。

play_audio

システムのデフォルトのオーディオプレーヤーを使用して、音量を指定して音声ファイルを再生します。

パラメーター：

• audioFile（string、必須）：再生する音声ファイルのパス
• volume（number、任意）：再生音量（パーセント、0～100）。指定しない場合は、環境変数 CHATTERBOX_PLAYBACK_VOLUME の値を使用します。環境変数も設定されていない場合のデフォルトは 50 です。

対応フォーマット：

• WAV ファイル（.wav）
• MP3 ファイル（.mp3）

戻り値：

• 再生ステータスとシステム情報を含む JSON レスポンス

レスポンス例：

{
  "success": true,
  "message": "Successfully played audio file: /tmp/local-voice-mcp/audio_123.wav",
  "audioFile": "/tmp/local-voice-mcp/audio_123.wav",
  "volume": 50,
  "platform": "darwin",
  "command": "afplay -v 0.5 /tmp/local-voice-mcp/audio_123.wav",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

プラットフォームのサポート：

• クロスプラットフォーム：すべてのプラットフォームで一貫した音量制御を行うため、ffplay（ffmpeg に含まれる）を優先します
• macOS：-v 音量フラグを指定して afplay コマンドにフォールバックします
• Windows：MediaPlayer と音量制御を使用する PowerShell にフォールバックします
• Linux：ゲイン制御付きの mpg123（MP3）または音量制御なしの aplay（WAV）にフォールバックします

tts_status

TTS サービスの現在のステータスを返します。

パラメーター： なし

戻り値：

• サービスのステータスと機能を含む JSON レスポンス

レスポンス例：

{
  "success": true,
  "status": "operational",
  "message": "TTS service is ready and operational",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": {
    "name": "Chatterbox TTS",
    "version": "0.1.0",
    "capabilities": [
      "text-to-speech synthesis",
      "voice cloning with reference audio",
      "prosody controls"
    ]
  }
}

MCP リソース

service-info

Local Voice MCP サービスに関する情報を提供します。

URI： local-voice://service-info

HTTP API

HTTP モードで実行すると、サーバーは次のエンドポイントを公開します。

POST /tts

ElevenLabs 互換のテキスト読み上げエンドポイントです。

ヘッダー：

• X-API-Key：API キー（認証用のプレースホルダー）
• Content-Type：application/json

リクエストボディ：

{
  "text": "[sigh] Hello, world! [laugh] This is great!",
  "options": {
    "referenceAudio": "path/to/reference.wav"
  }
}

レスポンス：

• Content-Type：audio/wav
• バイナリ音声データ

設定

環境変数

サーバー設定

• PORT：HTTP サーバーのポート（デフォルト：59125）
• MCP_MODE：動作モード（"mcp" または "http"、デフォルト："mcp"）

TTS エンジンの選択

• TTS_ENGINE：使用する TTS エンジン（"chatterbox"、"kani-mlx"、または "kokoro"、デフォルト："chatterbox"）

Chatterbox Turbo TTS の設定

以下の環境変数を使用して、Chatterbox Turbo TTS 音声合成のデフォルト値を設定できます。合成メソッドに渡されたオプションで上書きされない限り、これらの値が使用されます。

• PYTHON_PATH：Python インタープリターへのパス（デフォルト："python3"）。重要： Apple Silicon で Python 3.13 以降を使用する場合は、mlx-audio がインストールされている Python 3.11〜3.12 の conda 環境を指定してください。
• CHATTERBOX_REFERENCE_AUDIO：ボイスクローニング用の参照音声ファイルへのパス（システム上の任意の場所を指定でき、.wav、.mp3、.flac、.ogg、.m4a、.aac に対応）。指定しない場合は、同梱の高品質な女性の参照音声を使用します。
• USE_MALE_VOICE：同梱の女性の参照音声の代わりに男性の声を使用するかどうか（true/false、デフォルト：false）。true に設定すると、同梱の女性の声の代わりに Chatterbox のデフォルトの男性の声を使用します。カスタムの参照音声が指定されていない場合にのみ適用されます。
• CHATTERBOX_MAX_CHARACTERS：テキスト入力で許可される最大文字数（整数、デフォルト：2000）
• CHATTERBOX_OUTPUT_DIR：生成された音声ファイルの出力ディレクトリ（デフォルト：システムの一時ディレクトリ + "local-voice-mcp"）
• CHATTERBOX_PLAYBACK_VOLUME：音声再生のデフォルト音量（パーセント、整数、0〜100、デフォルト：50）

パラ言語タグ： プロソディ制御の代わりに、テキストにパラ言語タグを直接使用してください：[laugh]、[sigh]、[cough]、[chuckle]、[gasp]、[groan]、[clear throat]、[sniff]、[shush]

例： "[sigh] I can't believe it's Monday again. [laugh] But let's make the best of it!"

Kokoro の設定

以下の環境変数を使用して、Kokoro 音声合成のデフォルト値を設定できます。

• KOKORO_SPEED：読み上げ速度（浮動小数点数、0.5〜2.0、デフォルト：1.0）
• KOKORO_LANGUAGE：言語コード（文字列、デフォルト："en-us"）。対応言語：en-us、en-gb、fr-fr、it、ja、cmn
• KOKORO_VOICE：音声名（文字列、デフォルト："af_sarah"）。利用可能な音声については上記を参照してください。"voice1:weight,voice2:weight" のような音声ブレンド形式も使用できます。
• KOKORO_MODEL_PATH：kokoro ONNX モデルファイルへのパス（文字列、デフォルト："kokoro-v1.0.onnx"）
• KOKORO_VOICES_PATH：voices bin ファイルへのパス（文字列、デフォルト："voices-v1.0.bin"）
• KOKORO_MAX_CHARACTERS：テキスト入力で許可される最大文字数（整数、デフォルト：5000）
• KOKORO_OUTPUT_DIR：生成された音声ファイルの出力ディレクトリ（デフォルト：システムの一時ディレクトリ + "local-voice-mcp"）
• PYTHON_PATH：Python インタープリターへのパス（デフォルト："python3"）

例：

# Set default TTS parameters via environment variables
# Reference audio can be anywhere on your system
export CHATTERBOX_REFERENCE_AUDIO="/Users/john/Music/my-voice.wav"
export CHATTERBOX_MAX_CHARACTERS="3000"
export CHATTERBOX_PLAYBACK_VOLUME="75"

# Run the MCP server with these defaults
local-voice-mcp-server

npx を使用する場合：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "CHATTERBOX_REFERENCE_AUDIO": "/Users/john/Music/my-voice.wav",
        "CHATTERBOX_MAX_CHARACTERS": "3000",
        "CHATTERBOX_PLAYBACK_VOLUME": "75"
      }
    }
  }
}

同梱の女性の声の代わりに男性の声を使用する場合：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "USE_MALE_VOICE": "true"
      }
    }
  }
}

優先順位：

1. synthesize_text または play_audio ツールに渡されたオプション（最優先）
2. 環境変数
3. 組み込みのデフォルト値（優先度が最も低い）

MCP クライアントの設定

MCP クライアントの設定に追加してください：

{
  "local-voice-mcp": {
    "command": "npx",
    "args": ["-y", "local-voice-mcp-server"],
    "env": {}
  }
}

Cursor でのテスト

Cursor は MCP に対応した、人気の AI 搭載コードエディターです。Cursor で Local Voice MCP サーバーをテストする方法は次のとおりです。

1. パッケージをインストールする

まず、パッケージをグローバルにインストールするか、利用可能な状態にしてください：

npm install -g local-voice-mcp
# or
npm install local-voice-mcp

2. Cursor を設定する

MCP サーバーを Cursor の設定ファイルに追加します。保存場所はオペレーティングシステムによって異なります。

• macOS：~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json
• Windows：%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json
• Linux：~/.config/Cursor/User/globalStorage/cursor.mcp/config.json

次の設定を追加してください：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "local-voice-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

または、npx を使用する場合：

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "local-voice-mcp-server"],
      "env": {}
    }
  }
}

3. Cursor を再起動する

設定を追加した後、MCP サーバーを読み込むために Cursor を再起動します。

4. 統合をテストする

Cursor の再起動後、TTS 機能をテストできます。

1. Cursor の AI チャットを開きます

2. TTS ツールを使うよう Cursor に依頼します：

   Can you synthesize speech for "Hello, this is a test of the local voice MCP server"?
   

3. TTS のステータスを確認します：

   What's the status of the TTS service?
   

4. パラ言語タグを使ってテストします：

   Synthesize "[sigh] Welcome to the future of AI coding. [laugh] It's going to be amazing!"
   

5. 音声再生をテストします：

   Play the audio file that was just generated
   

6. 音量調整をテストします：

   Play the audio file at 25% volume
   

5. ツールが利用可能であることを確認する

Cursor で次のツールが利用可能になっていることを確認してください。

• synthesize_text - テキストを音声に変換します
• play_audio - システムのオーディオ経由で音声ファイルを再生します
• tts_status - サービスの状態を確認します

6. トラブルシューティング

MCP サーバーが Cursor に表示されない場合は、次の手順を試してください。

1. ログを確認する：Cursor の開発者コンソールでエラーメッセージを確認します
2. インストールを確認する：ターミナルで local-voice-mcp-server を直接実行し、正常に動作することを確認します
3. パスを確認する：設定内のコマンドパスが正しいことを確認します
4. Cursor を再起動する：設定を変更した後は、完全な再起動が必要な場合があります
5. JSON の解析エラー：「Unexpected token」エラーが表示される場合は、適切な stdio ログ記録に対応した最新バージョンを使用していることを確認します

7. 期待される動作

正常に動作している場合：

• Cursor から TTS ツールを呼び出せます
• ファイルパスを含む構造化 JSON レスポンスが返されます
• 音声ファイルは一時ディレクトリに保存されます
• TTS サービスは Chatterbox Turbo TTS エンジンを使用します
• システムのオーディオプレーヤーでファイルを再生できます

すべてのレスポンスは、明確なファイルパスを含む構造化 JSON 形式です。そのため、MCP クライアントと AI エージェントは結果を簡単に理解し、利用できます。

要件

• Node.js 16+
• Python 3.10-3.12（mlx-audio の依存関係では Python 3.13+ はまだサポートされていません）
• PyTorch（CUDA/CPU バックエンド用）
• Apple Silicon の場合：pip install mlx-audio
• CUDA/CPU の場合：pip install chatterbox-tts

Apple Silicon ユーザーへの重要な注意： mlx-audio パッケージは、依存関係の制約により Python <3.13 が必要です。システムの Python が 3.13+ の場合は、conda 環境を使用する必要があります。

# Create a Python 3.11 environment for Chatterbox
conda create -n chatterbox python=3.11
conda activate chatterbox
pip install mlx-audio

# Then set PYTHON_PATH in your MCP config to point to this environment

{
  "mcpServers": {
    "local-voice-mcp": {
      "command": "npx",
      "args": ["-y", "@codecraftersllc/local-voice-mcp"],
      "env": {
        "TTS_ENGINE": "chatterbox",
        "PYTHON_PATH": "/path/to/miniconda3/envs/chatterbox/bin/python"
      }
    }
  }
}

サービスはハードウェアを自動的に検出し、最適なバックエンドを使用します。

プラットフォーム	バックエンド	モデル
Apple Silicon（MLX 経由）	MLX	mlx-community/chatterbox-turbo-6bit
NVIDIA GPU（CUDA）	PyTorch	ChatterboxTurboTTS
CPU	PyTorch	ChatterboxTurboTTS（低速）

アーキテクチャ

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  HTTP Client     │    │   CLI Tool      │
│ (Cursor, etc.)  │    │                  │    │                 │
└─────────┬───────┘    └─────────┬────────┘    └─────────┬───────┘
          │                      │                       │
          │ stdio                │ HTTP                  │ stdio
          │                      │                       │
          ▼                      ▼                       ▼
    ┌─────────────────────────────────────────────────────────────┐
    │              Local Voice MCP Server                         │
    │  ┌─────────────────┐    ┌─────────────────────────────────┐ │
    │  │   MCP Server    │    │         HTTP Server             │ │
    │  │   (stdio)       │    │      (Express.js)               │ │
    │  └─────────────────┘    └─────────────────────────────────┘ │
    │                                   │                         │
    │  ┌─────────────────────────────────────────────────────────┐ │
    │  │              TTS Tools & Services                       │ │
    │  │  ┌─────────────────┐    ┌─────────────────────────────┐ │ │
    │  │  │ ChatterboxService│    │    File Management         │ │ │
    │  │  │                 │    │   (Cleanup & Security)     │ │ │
    │  │  └─────────────────┘    └─────────────────────────────┘ │ │
    │  └─────────────────────────────────────────────────────────┘ │
    └─────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                        ┌─────────────────────┐
                        │   Python TTS        │
                        │ (Chatterbox Turbo)  │
                        └─────────────────────┘

ライセンス

MIT

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 新しい機能のテストを追加します
5. すべてのテストが合格することを確認します
6. プルリクエストを送信します