MCP Voicevox Server

mcp voicevox服务器python

Claude Code 回话 VOICEVOX 朗读MCP (Model Context Protocol) 服务器。 根据日语的自然的合成声音，用耳朵能接受开发中的反馈。

______________________________________________________________________

🚀 概要

此项目包括：Claude Code 接受来自的指示Docker 在上面运行VOICEVOX Engine 通过声音生成，本地的 ffplay 中所述修改相应参数的值。

系统配置

• 客户端：克劳德代码
• MCP 服务器：Python（FastMCP）
• 发动机：VOICEVOX引擎（Docker）
• 玩家：ffplay（FFmpeg）

______________________________________________________________________

🛠 前提条件

• python: 3.10 以上
• 紫外线：包管理器（推荐）
• 码头工人: VOICEVOX Engine 执行所需
• FFmpeg：音频播放 ffplay 使用命令

- macOS： brew install ffmpeg - 窗户： choco install ffmpeg / scoop install ffmpeg - Linux： sudo apt install ffmpeg

______________________________________________________________________

📦 安装，安装

1.安装相关性

uv （建议）

uv sync

pip 中所述修改相应参数的值

pip install -r requirements.txt

______________________________________________________________________

⚙️ Claude Code 设定

~/.claude.json 将条目添加到文档注册表。

uv （建议）

{
  "mcpServers": {
    "voicevox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-voicevox-server", "python", "server.py"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "SPEAKER_ID": "3"
      }
    }
  }
}

python 来定义自定义外观

{
  "mcpServers": {
    "voicevox": {
      "command": "python3",
      "args": ["/path/to/mcp-voicevox-server/server.py"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "SPEAKER_ID": "3"
      }
    }
  }
}

环境变数

｜变量名｜说明｜默认｜ |--------|------|-----------| | VOICEVOX_URL | Engine 的地址 http://localhost:50021 | | SPEAKER_ID 角色ID | 3 | | AUTO_START_ENGINE 自动Docker是否启动 true |

角色一览（一部分）

四国目田 真没想到 春日部蜗牛

______________________________________________________________________

🐳 VOICEVOX Engine 自动启动

MCP 服务器启动时VOICEVOX Engine 未运行时，自动Docker 中所述修改相应参数的值。

机制

1. 服务器启动时 VOICEVOX_URL 检查到的连接
2. 无法连接时docker compose up -d 执行
3. Engine 启动前等待最多30秒

手动启动时

如果要禁用自动启动，请设置环境变量：

{
  "env": {
    "AUTO_START_ENGINE": "false"
  }
}

手动Docker 启动时：

# docker compose を使用
docker compose up -d

# または直接実行
docker run --rm -d -p 50021:50021 voicevox/voicevox_engine:cpu-ubuntu20.04-latest

______________________________________________________________________

🛠 提供的工具

speak_text

打开文本VOICEVOX 中选择新的扶手类型，来修改默认的扶手。

引数:

• text (string, 必需：要读的文本
• speed (number, optional): 语速（0.5〜2.0，默认：1.0）
• pitch (number, optional): 音高（-0.15到0.15，默认值：0.0）
• intonation (number, optional): 抑扬（0.0-2.0，默认值：1.0）
• volume (number, optional): 音量（0.0-2.0，默认值：1.0）

返回值：

• 播放完成消息或错误消息

save_audio

打开文本VOICEVOX 语音合成WAV 中所述修改相应参数的值。

引数:

• text (string, 必需：要读的文本
• output_path (string, 必需：目标文件路径（.wav）
• speed (number, optional): 语速（0.5〜2.0，默认：1.0）
• pitch (number, optional): 音高（-0.15到0.15，默认值：0.0）
• intonation (number, optional): 抑扬（0.0-2.0，默认值：1.0）
• volume (number, optional): 音量（0.0-2.0，默认值：1.0）

返回值：

• 保存完成消息或错误消息

______________________________________________________________________

💡 用法

Claude Code 请在上面直接指示。

「今のコード変更の概要を speak_text で教えて」
「テストが通ったら『お疲れ様なのだ』と喋って」

自动化提示

.claude/settings.json 啊 CLAUDE.md 添加以下系统提示：

每个回答的最后一定要speak_text 请使用工具在一句话中朗读回答的重要要点。

______________________________________________________________________

📝 许可证

麻省理工学院