# VOICEVOX TTS MCP
[English](README.md) | **日本語**
VOICEVOX を使用した MCP テキスト読み上げサーバー
## 何ができるか
- **AI アシスタントに喋らせる** — Claude Desktop などの MCP クライアントからテキストを読み上げ
- **複数キャラクターの会話** — 1 回の呼び出しでセグメントごとに話者を切り替え可能
- **スムーズな再生** — キュー管理、即時再生、先読み、ストリーミング再生
- **クロスプラットフォーム** — Windows, macOS, Linux（WSL 含む）で動作
## クイックスタート
### 必要なもの
- Node.js 18.0.0 以上
- [VOICEVOX Engine](https://voicevox.hiroshiba.jp/)（起動しておく）
- ffplay（任意・推奨）
#### FFplay の導入
ffplay は FFmpeg に同梱される小型プレイヤーで、標準入力からの再生に対応します。導入済みの環境では、低遅延で安定したストリーミング再生を自動的に使用します。
> 💡 **ffplay がなくても動作します。** その場合は一時ファイル経由の再生（Windows: PowerShell、macOS: afplay、Linux: aplay 等）にフォールバックします。
- 導入は簡単: 各 OS でワンライナーのセットアップ（下記手順）
- 必須事項: `ffplay` に PATH が通っている必要があります（導入後に端末/アプリ再起動）
<details>
<summary>FFplay の導入手順と PATH 反映</summary>
インストール例:
- Windows（いずれか）
- Winget: `winget install --id=Gyan.FFmpeg -e`
- Chocolatey: `choco install ffmpeg`
- Scoop: `scoop install ffmpeg`
- 公式ビルド（例）: https://www.gyan.dev/ffmpeg/builds/ または https://github.com/BtbN/FFmpeg-Builds から zip を取得し、`bin` フォルダを PATH に追加
- macOS
- Homebrew: `brew install ffmpeg`
- Linux
- Debian/Ubuntu: `sudo apt-get update && sudo apt-get install -y ffmpeg`
- Fedora: `sudo dnf install -y ffmpeg`
- Arch: `sudo pacman -S ffmpeg`
PATH の反映:
- Windows: 環境変数に `...\ffmpeg\bin` を追加後、PowerShell/端末・エディタ（Claude/VS Code 等）を再起動。
- 反映確認: `powershell -c "$env:Path"` に ffmpeg のパスが含まれること
- macOS/Linux: 通常は自動反映。必要に応じて `echo $PATH` で確認し、シェルを再起動。
- MCP クライアント（Claude Desktop/Code）: アプリ側のプロセス再起動で PATH を再読込します。
動作確認:
```bash
ffplay -version
```
バージョン情報が表示されれば導入完了です。CLI/MCP は自動的に ffplay を検出して標準入力ストリーミング再生を使用します。
</details>
### 3 ステップで開始
**1. VOICEVOX Engine を起動**
**2. Claude Desktop の設定ファイルに追加**
設定ファイルの場所:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"tts-mcp": {
"command": "npx",
"args": ["-y", "@kajidog/mcp-tts-voicevox"]
}
}
}
```
**3. Claude Desktop を再起動**
これだけで Claude に「〇〇と喋って」と頼めば喋ってくれます！
---
## MCP ツール
### `speak` — テキスト読み上げ
Claude から呼び出せるメインの機能です。
| パラメータ | 説明 | デフォルト |
|-----------|------|-----------|
| `text` | 読み上げるテキスト（改行で複数セグメント） | 必須 |
| `speaker` | 話者 ID | 1 |
| `speedScale` | 再生速度 | 1.0 |
| `immediate` | 即時再生（キューをクリア） | true |
| `waitForEnd` | 再生完了まで待機 | false |
**使用例：**
```javascript
// シンプルなテキスト
{ "text": "こんにちは" }
// 話者を指定
{ "text": "こんにちは", "speaker": 3 }
// セグメントごとに話者を変更
{ "text": "1:こんにちは\n3:今日はいい天気ですね" }
// 再生完了まで待機（同期処理）
{ "text": "このメッセージを読み終えてから次へ", "waitForEnd": true }
```
<details>
<summary>その他のツール</summary>
| ツール | 説明 |
|--------|------|
| `ping_voicevox` | VOICEVOX Engine への接続確認 |
| `get_speakers` | 利用可能な話者一覧を取得 |
| `get_speaker_detail` | 話者の詳細情報を取得 |
| `stop_speaker` | 再生停止とキューのクリア |
| `generate_query` | 音声合成クエリを生成 |
| `synthesize_file` | 音声ファイルを生成 |
</details>
---
## 設定
<details>
<summary><b>環境変数で設定</b></summary>
### VOICEVOX 設定
| 環境変数 | 説明 | デフォルト |
|---------|------|-----------|
| `VOICEVOX_URL` | Engine の URL | `http://localhost:50021` |
| `VOICEVOX_DEFAULT_SPEAKER` | デフォルト話者 ID | `1` |
| `VOICEVOX_DEFAULT_SPEED_SCALE` | 再生速度 | `1.0` |
### 再生オプション
| 環境変数 | 説明 | デフォルト |
|---------|------|-----------|
| `VOICEVOX_USE_STREAMING` | ストリーミング再生（`ffplay` 必要） | `false` |
| `VOICEVOX_DEFAULT_IMMEDIATE` | 即時再生 | `true` |
| `VOICEVOX_DEFAULT_WAIT_FOR_START` | 再生開始まで待機 | `false` |
| `VOICEVOX_DEFAULT_WAIT_FOR_END` | 再生完了まで待機 | `false` |
### 制限設定
AI が特定のオプションを指定できないように制限できます。
| 環境変数 | 説明 |
|---------|------|
| `VOICEVOX_RESTRICT_IMMEDIATE` | `immediate` オプションを制限 |
| `VOICEVOX_RESTRICT_WAIT_FOR_START` | `waitForStart` オプションを制限 |
| `VOICEVOX_RESTRICT_WAIT_FOR_END` | `waitForEnd` オプションを制限 |
### ツールの無効化
```bash
# 不要なツールを無効化
export VOICEVOX_DISABLED_TOOLS=generate_query,synthesize_file
```
### サーバー設定
| 環境変数 | 説明 | デフォルト |
|---------|------|-----------|
| `MCP_HTTP_MODE` | HTTP モードを有効化 | `false` |
| `MCP_HTTP_PORT` | HTTP ポート | `3000` |
| `MCP_HTTP_HOST` | HTTP ホスト | `0.0.0.0` |
| `MCP_ALLOWED_HOSTS` | 許可するホスト（カンマ区切り） | `localhost,127.0.0.1,[::1]` |
| `MCP_ALLOWED_ORIGINS` | 許可するオリジン（カンマ区切り） | `http://localhost,http://127.0.0.1,...` |
</details>
<details>
<summary><b>コマンドライン引数で設定</b></summary>
コマンドライン引数は環境変数より優先されます。
```bash
# 基本設定
npx @kajidog/mcp-tts-voicevox --url http://192.168.1.100:50021 --speaker 3 --speed 1.2
# HTTP モード
npx @kajidog/mcp-tts-voicevox --http --port 8080
# 制限付き
npx @kajidog/mcp-tts-voicevox --restrict-immediate --restrict-wait-for-end
# ツール無効化
npx @kajidog/mcp-tts-voicevox --disable-tools generate_query,synthesize_file
```
| 引数 | 説明 |
|------|------|
| `--help`, `-h` | ヘルプを表示 |
| `--version`, `-v` | バージョンを表示 |
| `--url <value>` | VOICEVOX Engine URL |
| `--speaker <value>` | デフォルト話者 ID |
| `--speed <value>` | 再生速度 |
| `--use-streaming` / `--no-use-streaming` | ストリーミング再生 |
| `--immediate` / `--no-immediate` | 即時再生 |
| `--wait-for-start` / `--no-wait-for-start` | 再生開始待機 |
| `--wait-for-end` / `--no-wait-for-end` | 再生完了待機 |
| `--restrict-immediate` | immediate を制限 |
| `--restrict-wait-for-start` | waitForStart を制限 |
| `--restrict-wait-for-end` | waitForEnd を制限 |
| `--disable-tools <tools>` | ツールを無効化 |
| `--http` | HTTP モード |
| `--port <value>` | HTTP ポート |
| `--host <value>` | HTTP ホスト |
| `--allowed-hosts <hosts>` | 許可するホスト（カンマ区切り） |
| `--allowed-origins <origins>` | 許可するオリジン（カンマ区切り） |
</details>
<details>
<summary><b>HTTP モードで使う</b></summary>
リモート接続が必要な場合：
**サーバー起動：**
```bash
# Linux/macOS
MCP_HTTP_MODE=true MCP_HTTP_PORT=3000 npx @kajidog/mcp-tts-voicevox
# Windows PowerShell
$env:MCP_HTTP_MODE='true'; $env:MCP_HTTP_PORT='3000'; npx @kajidog/mcp-tts-voicevox
```
**Claude Desktop 設定（mcp-remote 使用）：**
```json
{
"mcpServers": {
"tts-mcp-proxy": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
}
}
}
```
</details>
<details>
<summary><b>WSL から Windows ホストに接続</b></summary>
WSL 内から Windows で動作する MCP サーバーに接続する場合：
### 1. WSL 側で Windows ホストの IP を確認
```bash
# 方法1: デフォルトゲートウェイから取得
ip route show | grep -oP 'default via \K[\d.]+'
# 通常 172.x.x.1 の形式
# 方法2: /etc/resolv.conf から取得（WSL2）
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
```
### 2. Windows 側でサーバー起動
WSL からのアクセスを許可するため、`MCP_ALLOWED_HOSTS` に WSL ゲートウェイ IP を追加：
```powershell
$env:MCP_HTTP_MODE='true'
$env:MCP_ALLOWED_HOSTS='localhost,127.0.0.1,172.29.176.1'
npx @kajidog/mcp-tts-voicevox
```
または CLI 引数で：
```powershell
npx @kajidog/mcp-tts-voicevox --http --allowed-hosts "localhost,127.0.0.1,172.29.176.1"
```
### 3. WSL 側の設定（.mcp.json）
```json
{
"mcpServers": {
"tts": {
"type": "http",
"url": "http://172.29.176.1:3000/mcp"
}
}
}
```
> ⚠️ WSL 内では `localhost` は WSL 自身を指すため、Windows ホストには WSL ゲートウェイ IP でアクセスします。
</details>
---
## トラブルシューティング
<details>
<summary><b>音声が再生されない</b></summary>
**1. VOICEVOX Engine が起動しているか確認**
```bash
curl http://localhost:50021/speakers
```
**2. プラットフォーム別の再生ツールを確認**
| OS | 必要なツール |
|----|------------|
| Linux | `aplay`, `paplay`, `play`, `ffplay` のいずれか |
| macOS | `afplay`（プリインストール済み） |
| Windows | PowerShell（プリインストール済み） |
</details>
<details>
<summary><b>MCP クライアントに認識されない</b></summary>
- パッケージのインストール確認：`npm list -g @kajidog/mcp-tts-voicevox`
- 設定ファイルの JSON 構文をチェック
- クライアントを再起動
</details>
---
## パッケージ構成
| パッケージ | 説明 |
|-----------|------|
| `@kajidog/mcp-tts-voicevox` | MCP サーバー本体 |
| [`@kajidog/voicevox-client`](https://www.npmjs.com/package/@kajidog/voicevox-client) | 汎用 VOICEVOX クライアントライブラリ（独立使用可能） |
---
<details>
<summary><b>開発者向け情報</b></summary>
### セットアップ
```bash
git clone https://github.com/kajidog/mcp-tts-voicevox.git
cd mcp-tts-voicevox
pnpm install
```
### コマンド
| コマンド | 説明 |
|---------|------|
| `pnpm build` | 全パッケージをビルド |
| `pnpm test` | テスト実行 |
| `pnpm lint` | Lint 実行 |
| `pnpm dev` | 開発サーバー起動 |
| `pnpm dev:stdio` | Stdio モードで開発 |
</details>
---
## ライセンス
ISC
