# VOICEVOX MCP Server

macOS (Apple Silicon / arm64) 環境向けの GUI 不要な VOICEVOX Engine スタンドアローン版のセットアップおよび、VOICEVOX を利用してテキスト読み上げ・話者一覧取得を行う Model Context Protocol (MCP) サーバーです。

---

## 構成・特徴

- **GUI 不要**: バックグラウンドまたはターミナルから VOICEVOX Engine を起動して運用可能。
- **FastMCP 実装**: 公式 MCP Python SDK (`FastMCP`) を使用し、Claude Desktop や Antigravity 等の MCP クライアントからツールとして直接呼び出し可能。
- **macOS 標準再生**: 合成された音声は一時 WAV ファイル (`/tmp/voicevox_output.wav`) に出力され、macOS 標準の `afplay` で即座に再生。

---

## 提供ツール (MCP Tools)

| ツール名 | 引数 | 説明 |
| :--- | :--- | :--- |
| `speak_text` | `text: str`<br>`speaker: int = 2`<br>`speed: float = 1.3` | 指定したテキストを音声合成し、Mac のスピーカーから再生します。<br>- デフォルトの話者: `2` (四国めたん ノーマル)<br>- `speed`: 話速倍率 (デフォルト: `1.3`, 標準速度: `1.0`, より早口: `1.5`, ゆっくり: `0.8`〜`0.9`) |
| `get_speakers` | なし | VOICEVOX Engine に登録されている全キャラクターおよびスタイル名・ID（speaker ID）の一覧を返します。 |

---

## セットアップ手順

### 1. 依存ツールのインストール (Homebrew)
7z アーカイブの展開用に `p7zip` または `sevenzip` をインストールします。
```bash
brew install p7zip
```

### 2. VOICEVOX Engine スタンドアローン版のセットアップ
セットアップスクリプトを実行します。
```bash
./scripts/setup_engine.sh
```
※ スクリプトは以下の優先順でエンジンバイナリを `engine/` ディレクトリに配置します：
1. 引数で指定されたパス (`./scripts/setup_engine.sh /path/to/archive_or_dir`)
2. カレントディレクトリまたは `~/Downloads` にある `voicevox_engine-macos-arm64-*.7z.001`
3. 既存のローカルインストール (`/Applications/VOICEVOX.app/Contents/Resources/vv-engine`)
4. GitHub Releases (`VOICEVOX/voicevox_engine`) からの自動ダウンロード

### 3. Python 仮想環境のセットアップ
```bash
# Python 3.10 による仮想環境作成と依存関係のインストール
python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## 使い方

### 1. VOICEVOX Engine の起動
```bash
./scripts/start_engine.sh
```
- デフォルトで `http://127.0.0.1:50021` で起動します。
- 既に別プロセスや GUI 版 VOICEVOX が同一ポートで動作している場合は、自動検知して既存インスタンスを利用します。

起動確認:
```bash
curl http://127.0.0.1:50021/version
# => "0.25.2"
```

### 2. Web フロントエンド（GUIスタジオ）の起動

#### 方法 A: ダブルクリックで起動（最も簡単）
Finder でプロジェクトフォルダ内の **`start.command`** をダブルクリックするだけです。
自動的にエンジンとサーバーが起動し、ブラウザでスタジオ画面が開きます。

#### 方法 B: ターミナルから起動
```bash
./scripts/start_web.sh
```
ブラウザで **`http://127.0.0.1:8000`** を開きます。
- **話者プルダウン**: 四国めたん、ずんだもん等、全キャラクター・スタイルを動的選択
- **パラメータスライダー**: 話速（初期値 1.3）、音高、抑揚、音量をリアルタイム微調整
- **改行による行分割出力**: テキストエリア内の改行に応じて、`outputs/output-001.wav`, `output-002.wav` ... と連番ファイルを一括自動生成
- **再生・ダウンロード**: 各行のブラウザ内プレビュー再生、個別WAV保存、全ファイル一括ZIP保存に対応

### 3. サービスの停止方法
- **ダブルクリックで停止**: **`stop.command`** をダブルクリックするだけです。
- **ターミナルから停止**: `./scripts/stop.sh` を実行します。
- フォアグラウンド実行中の場合はターミナルで `Ctrl + C` を押すだけでも停止できます。

### 4. MCP クライアントへの登録

#### Claude Desktop / Antigravity 等の設定例

設定ファイル（例: `~/Library/Application Support/Claude/claude_desktop_config.json` 等）に以下を追加します：

```json
{
  "mcpServers": {
    "voicevox": {
      "command": "/Users/yoshimana/Documents/project/voicevox_mcp/.venv/bin/python",
      "args": [
        "/Users/yoshimana/Documents/project/voicevox_mcp/voicevox_mcp.py"
      ],
      "env": {
        "VOICEVOX_ENGINE_URL": "http://127.0.0.1:50021"
      }
    }
  }
}
```

> [!TIP]
> 仮想環境の Python インタプリタパス（`.venv/bin/python`）を指定することで、グローバル環境を汚さず安定して動作します。

---

## ファイル構成

```text
voicevox_mcp/
├── README.md                  # 本ドキュメント
├── requirements.txt           # Python 依存関係 (mcp, requests)
├── voicevox_mcp.py            # FastMCP サーバー本体
├── .gitignore                 # バージョン管理除外設定
├── engine/                    # VOICEVOX Engine スタンドアローンバイナリ (gitignore対象)
└── scripts/
    ├── setup_engine.sh        # エンジン取得・解凍スクリプト
    └── start_engine.sh        # エンジン起動・ヘルスチェックスクリプト
```

---

制作者・お問い合わせ:[ɐuɐɯı̣ɥsoʎ (@yoshimana) ↗](https://x.com/yoshimana)