mcp-voicevox-server

# mcp-voicevox-server-python MCP (Model Context Protocol) server to read Claude Code's responses with **VOICEVOX**. It allows you to receive feedback during development by ear with natural synthesized Japanese speech. --- ## 🚀 Overview This project receives instructions from Claude Code, generates speech through the VOICEVOX Engine running on Docker, and plays it with local `ffplay`. ### System Configuration - **Client**: Claude Code - **MCP Server**: Python (FastMCP) - **Engine**: VOICEVOX Engine (Docker) - **Player**: ffplay (FFmpeg) --- ## 🛠 Prerequisites - **Python**: 3.10 or higher - **uv**: Package manager (recommended) - **Docker**: Required to run VOICEVOX Engine - **FFmpeg**: Use the `ffplay` command for audio playback - macOS: `brew install ffmpeg` - Windows: `choco install ffmpeg` / `scoop install ffmpeg` - Linux: `sudo apt install ffmpeg` --- ## 📦 Setup ### 1. Install Dependencies #### Using uv (recommended) ```bash uv sync ``` #### Using pip ```bash pip install -r requirements.txt ``` --- ## ⚙️ Claude Code Configuration Add the following configuration to `~/.claude.json`. ### Using uv (recommended) ```json { "mcpServers": { "voicevox": { "command": "uv", "args": ["run", "--directory", "/path/to/mcp-voicevox-server", "python", "server.py"], "env": { "VOICEVOX_URL": "http://localhost:50021", "SPEAKER_ID": "3" } } } } ``` ### Using python directly ```json { "mcpServers": { "voicevox": { "command": "python3", "args": ["/path/to/mcp-voicevox-server/server.py"], "env": { "VOICEVOX_URL": "http://localhost:50021", "SPEAKER_ID": "3" } } } } ``` ### Environment Variables | Variable Name | Description | Default | |---------------|-------------|---------| | `VOICEVOX_URL` | Engine address | `http://localhost:50021` | | `SPEAKER_ID` | Character ID | `3` | | `AUTO_START_ENGINE` | Whether to automatically start Docker | `true` | ### Character List (Partial) | ID | Character | |----|-----------| | 2 | 四国めたん | | 3 | ずんだもん | | 8 | 春日部つむぎ | --- ## 🐳 Automatically Start VOICEVOX Engine If the VOICEVOX Engine is not running when the MCP server starts, it will automatically start with Docker. ### Mechanism 1. Check the connection to `VOICEVOX_URL` when the server starts 2. If the connection fails, execute `docker compose up -d` 3. Wait up to 30 seconds for the Engine to start ### Manual Startup If you want to disable automatic startup, set the environment variable: ```json { "env": { "AUTO_START_ENGINE": "false" } } ``` To start Docker manually: ```bash # Using docker compose docker compose up -d # Or execute directly docker run --rm -d -p 50021:50021 voicevox/voicevox_engine:cpu-ubuntu20.04-latest ``` --- ## 🛠 Provided Tools ### `speak_text` Synthesizes text with VOICEVOX and plays it from the speaker. **Arguments:** - `text` (string, required): Text to be read - `speed` (number, optional): Speaking speed (0.5 〜 2.0, default: 1.0) - `pitch` (number, optional): Pitch (-0.15 〜 0.15, default: 0.0) - `intonation` (number, optional): Intonation (0.0 〜 2.0, default: 1.0) - `volume` (number, optional): Volume (0.0 〜 2.0, default: 1.0) **Return Value:** - Playback completion message or error message ### `save_audio` Synthesizes text with VOICEVOX and saves it as a WAV file. **Arguments:** - `text` (string, required): Text to be read - `output_path` (string, required): File path to save to (.wav) - `speed` (number, optional): Speaking speed (0.5 〜 2.0, default: 1.0) - `pitch` (number, optional): Pitch (-0.15 〜 0.15, default: 0.0) - `intonation` (number, optional): Intonation (0.0 〜 2.0, default: 1.0) - `volume` (number, optional): Volume (0.0 〜 2.0, default: 1.0) **Return Value:** - Save completion message or error message --- ## 💡 Usage Give instructions directly on Claude Code. ``` "Tell me the overview of the current code changes with speak_text" "Speak 'Good job' when the test passes" ``` ### Automation Tips It is useful to add the following system prompt to `.claude/settings.json` or `CLAUDE.md`: > Always use the speak_text tool at the end of each response to read out the key points of the response in one sentence. --- ## 📝 License MIT