# vv-mcp
VOICEVOX MCP Server - Claude DesktopとClaude
Codeで音声合成を利用するためのMCPサーバー
## 必要要件
- Node.js 18以上
- [VOICEVOX](https://voicevox.hiroshiba.jp/)がインストールされ、起動していること
- サポートOS:
- **macOS**: `afplay`を使用（追加インストール不要）
- **Linux**: `paplay`（PulseAudio）が必要
- Arch Linux: `pacman -S pulseaudio`
- Ubuntu/Debian: `apt install pulseaudio-utils`
- Fedora: `dnf install pulseaudio-utils`
## インストール
### npmからインストール（推奨）
```bash
npm install -g @arrow2nd/vv-mcp
```
### ソースからビルド
```bash
git clone https://github.com/arrow2nd/vv-mcp.git
cd vv-mcp
npm install
npm run build
```
## Claude Desktopでの設定
設定ファイルを編集：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
### npmでインストールした場合
```json
{
"mcpServers": {
"vv-mcp": {
"command": "npx",
"args": ["-y", "@arrow2nd/vv-mcp"],
"env": {
"VOICEVOX_URL": "http://localhost:50021",
"DEFAULT_VOICE_ID": "47",
"DEFAULT_SPEED": "1.0"
}
}
}
}
```
### ソースからビルドした場合
```json
{
"mcpServers": {
"vv-mcp": {
"command": "node",
"args": ["/path/to/vv-mcp/dist/index.js"],
"env": {
"VOICEVOX_URL": "http://localhost:50021",
"DEFAULT_VOICE_ID": "47",
"DEFAULT_SPEED": "1.0"
}
}
}
}
```
## Claude Codeでの設定
`~/.claude.json`の`mcpServers`セクションに以下を追加：
### npx/bunxを使用する場合（推奨）
```json
{
"mcpServers": {
"vv-mcp": {
"command": "npx",
"args": ["-y", "@arrow2nd/vv-mcp"],
"env": {
"VOICEVOX_URL": "http://localhost:50021",
"DEFAULT_VOICE_ID": "47",
"DEFAULT_SPEED": "1.0"
}
}
}
}
```
bunxを使用する場合は`"command": "bunx"`に変更してください。
### ソースからビルドした場合
```json
{
"mcpServers": {
"vv-mcp": {
"command": "node",
"args": ["/path/to/vv-mcp/dist/index.js"],
"env": {
"VOICEVOX_URL": "http://localhost:50021",
"DEFAULT_VOICE_ID": "47",
"DEFAULT_SPEED": "1.0"
}
}
}
}
```
## 使用方法
Claude Desktop/Codeを再起動後、以下のMCPツールが利用可能になります：
### 利用可能なツール
- `say` - テキストを音声合成して再生（非同期実行）
- `list_voices` - 利用可能な音声一覧を取得
- `get_queue_status` - 再生キューの状態を確認
- `clear_queue` - 再生キューをクリア
- `get_voices_in_use` - 現在使用中の音声IDのリストを取得（全プロセス共通）
- `get_random_unused_voice` - 使用されていない音声をランダムに1つ取得
- `get_session_voice` - このセッションで使用する音声を取得（セッション毎に固定）
### 使用例
```
「こんにちは」と言って
```
```
ナースロボの楽々な声で「完了しました」と言って
```
```
利用可能な音声を教えて
```
## セッション音声機能
各Claudeセッションに固定の音声を自動割り当てする機能があります：
### 使用方法
```
# セッション音声を使用して読み上げ
"こんにちは"とセッション音声で言って
```
### sayツールのパラメータ
- `useSessionVoice: true` - セッション音声を使用（voiceIdは無視される）
- `useSessionVoice: false`（デフォルト） -
指定した音声IDまたはデフォルト音声を使用
### 仕組み
- セッション開始時に自動的に音声を選択
- 他のセッションと重複しない音声を優先的に選択
- 全音声が使用中の場合は使用頻度の低い音声を選択
- セッション終了時に自動的に音声を解放
## 複数インスタンス対応
複数のClaude
Desktop/Codeが同時に動作している場合、自動的に異なる音声を使用して音声の重複を避けます。
- 各プロセスで使用中の音声情報を共有
- `get_random_unused_voice`ツールで未使用の音声を自動選択
- 一時ディレクトリに状態ファイルを作成して情報を共有
## 環境変数
| 変数名 | デフォルト値 | 説明 |
| ---------------- | ------------------------ | ----------------------------------------- |
| VOICEVOX_URL | http://localhost:50021 | VOICEVOX APIのURL |
| DEFAULT_VOICE_ID | 47 | デフォルトの音声ID (ナースロボ＿タイプＴ) |
| DEFAULT_SPEED | 1.0 | デフォルトの話速 |
| VV_MCP_STATE_DIR | システム一時ディレクトリ | 共有状態ファイルの保存ディレクトリ |
## ライセンス
MIT
