Vv MCP

vv mcp

VOICEVOX MCP Server-Claude Desktop和Claude 用于在Code中利用语音合成的MCP服务器

必要要件

• Node.js 18以上
• VOICEVOX已安装并启动
• 支持操作系统：

- macOS: afplay使用（无需额外安装） - Linux: paplay（PulseAudio） - Arch Linux： pacman -S pulseaudio - Ubuntu/Debian： apt install pulseaudio-utils - Fedora： dnf install pulseaudio-utils - 视窗：使用PowerShell（无需额外安装）

安装

从npm安装（推荐）

npm install -g @arrow2nd/vv-mcp

从源构建

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
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

使用npm安装时

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

从源构建时

{
  "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时（推荐）

{
  "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"中所述修改相应参数的值。

从源构建时

{
  "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 -随机获取一个未使用的语音
• get_session_voice -获取要在此会话中使用的语音（每个会话固定）

使用例

「こんにちは」と言って

ナースロボの楽々な声で「完了しました」と言って

利用可能な音声を教えて

会话语音功能

为每个Claude会话自动分配固定语音：

使用方法

# セッション音声を使用して読み上げ
"こんにちは"とセッション音声で言って

say工具参数

• useSessionVoice: true -使用会话语音（voiceId被忽略）
• useSessionVoice: false（默认值）-

使用指定的语音ID或默认语音

机制

• 会话开始时自动选择语音
• 优先选择与其他会话不重复的语音
• 在所有声音都在使用中的情况下选择使用频度低的声音
• 会话结束时自动释放语音

多实例支持

多个Claude 如果桌面/代码同时工作，则自动使用不同的声音避免重复的声音。

• 共享每个进程正在使用的语音信息
• get_random_unused_voice自动选择工具中未使用的音频
• 在临时目录中创建状态文件以共享信息

环境变数

｜变量名｜默认值｜说明｜ | ---------------- | ------------------------ | ----------------------------------------- | |voicex_URL|http://localhost:50021| VOICEVOX APIのURL| 默认语音ID（护士机器人类型T） 默认语速 系统临时目录共享状态文件的保存目录

许可证

麻省理工学院