mcp-tts-voicevox

This MCP server adds VOICEVOX text-to-speech capabilities to MCP clients via the VoiceVox MCP tools. The primary callable tool is voicevox_speak, which converts text into speech using VOICEVOX voices and returns audio data for playback in chat clients. For a richer experience, you can use speak_player to launch an interactive UI audio player inside the chat (via MCP Apps), allowing multi-speaker playback, per-segment editing, WAV export, and client-side audio rendering. Additional tools like resynthesize_player, get_player_state, and open_dictionary_ui enable updating existing player sessions, inspecting playback state, and managing the VOICEVOX user dictionary, respectively. The server supports multi-speaker dialogue within a single call and queues/streams playback to ensure smooth audio delivery to end users across supported MCP clients (ChatGPT, Claude Desktop, etc.).

To use the UI Audio Player, ensure your client and environment support MCP Apps. The player runs in the browser or a host app and streams audio to the client, keeping server-side resources free of audio rendering responsibilities. When using the Docker deployment, remember that audio playback on the server side may be disabled by default, so the client-side player is recommended for all playback scenarios. If your client requires a player domain for routing, set VOICEVOX_PLAYER_DOMAIN accordingly. You can integrate with Claude Desktop by embedding the MCP server into Claude’s config and pointing to the server’s endpoint or to mcp-remote when using Docker Compose.

Prerequisites:

• Node.js 18.0.0 or higher (or Bun) or Docker
• VOICEVOX Engine running (or via Docker Compose)
• ffplay (optional for low-latency streaming; required for certain playback modes if available)

Install (Node/npm):

1. Ensure Node.js is installed on your system.
2. Install and run the MCP server via npx (as shown in the Quick Start example):

npx -y @kajidog/mcp-tts-voicevox

3. If you prefer Bun, replace npx with bunx in your Claude Desktop config as shown in the Quick Start:

"command": "bunx", "args": ["@kajidog/mcp-tts-voicevox"]

Docker (quick start):

1. Use the provided docker-compose setup to run both VOICEVOX Engine and the MCP server:

docker compose up -d

2. In Claude Desktop, configure the MCP server with mcp-remote pointing to http://localhost:3000/mcp as shown in the Quick Start.

Prerequisites for Docker:

• Docker and Docker Compose installed
• Optional: VOICEVOX Engine and its VOICEVOX Install etc. If using Docker Compose, these services are started automatically.

Testing:

• After starting, you can send a speak call via MCP to generate audio and test playback in your client.

Tips and common issues:

• If using the UI Audio Player, ensure VOICEVOX_PLAYER_DOMAIN is set when required by the client (for example, to enable client-side playback in certain environments).
• In Docker environments without an audio device, the server-side playback tool (voicevox_speak) is disabled by default; prefer voicevox_speak_player for client-side playback.
• FFplay is optional but recommended for low-latency streaming. If you install FFplay manually, ensure it’s on your system PATH and restart your terminal/app after installation.
• The server supports multi-speaker tracks and per-segment edits, including speed, volume, and pitch. Use open_dictionary_ui to manage VOICEVOX dictionary words and preview them in-app.
• When using Bun or npx, ensure you’re using compatible versions to avoid path or module resolution issues. If you see network or permission errors with npx, try clearing npm cache or running with elevated permissions.
• For cross-user sessions, the resynthesize_player tool regenerates audio for all segments and returns a new viewUUID; use get_player_state to inspect current playback state if tuning AI parameters.