VOICEVOX TTS MCP

English | 日本語

A text-to-speech MCP server using VOICEVOX

🎮 Try the Browser Demo — Test VoicevoxClient directly in your browser

What You Can Do

• Make your AI assistant speak — Text-to-speech from MCP clients like Claude Desktop

• UI Audio Player (MCP Apps) — Play audio directly in the chat with an interactive player

• Multi-character conversations — Switch speakers per segment in a single call

• Smooth playback — Queue management, immediate playback, prefetching, streaming

• Cross-platform — Works on Windows, macOS, Linux (including WSL)

UI Audio Player (MCP Apps)

The voicevox_speak_player tool uses MCP Apps to render an interactive audio player directly inside the chat. Unlike the standard voicevox_speak tool which plays audio on the server, audio is played on the client side (in the browser/app) — no audio device needed on the server.

Features

• Client-side playback — Audio plays in Claude Desktop's chat, not on the server. Works even over remote connections.

• Play/Pause controls — Full playback controls embedded in the conversation

• Multi-speaker dialogue — Sequential playback of multiple speakers in one player with track navigation

• Speaker switching — Change the voice of any segment directly from the player UI

Note: voicevox_speak_player requires a host that supports MCP Apps (e.g., Claude Desktop). In hosts without MCP Apps support, the tool is not available and voicevox_speak (server-side playback) can be used instead.

Quick Start

Requirements

• Node.js 18.0.0 or higher (or Bun) or Docker

• VOICEVOX Engine (must be running; included in Docker Compose)

• ffplay (optional, recommended — not needed with Docker)

Installing FFplay

ffplay is a lightweight player included with FFmpeg that supports playback from stdin. When available, it automatically enables low-latency streaming playback.

💡 FFplay is optional. Without it, playback falls back to temp file-based playback (Windows: PowerShell, macOS: afplay, Linux: aplay, etc.).

• Easy setup: One-liner installation for each OS (see steps below)

• Required: ffplay must be in PATH (restart terminal/apps after installation)

Installation examples:

• Windows (any of these)

  • Winget: winget install --id=Gyan.FFmpeg -e

  • Chocolatey: choco install ffmpeg

  • Scoop: scoop install ffmpeg

  • Official builds: Download from https://www.gyan.dev/ffmpeg/builds/ or https://github.com/BtbN/FFmpeg-Builds and add the bin folder to PATH

• macOS

  • Homebrew: brew install ffmpeg

• Linux

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y ffmpeg

  • Fedora: sudo dnf install -y ffmpeg

  • Arch: sudo pacman -S ffmpeg

PATH Setup:

• Windows: Add ...\ffmpeg\bin to environment variables, then restart PowerShell/terminal and editor (Claude/VS Code, etc.)

  • Verify: powershell -c "$env:Path" should include the ffmpeg path

• macOS/Linux: Usually auto-detected. Check with echo $PATH if needed, restart shell.

• MCP clients (Claude Desktop/Code): Restart the app to reload PATH.

Verification:

If version info is displayed, installation is complete. CLI/MCP will automatically detect ffplay and use stdin streaming playback.

3 Steps to Get Started

1. Start VOICEVOX Engine

2. Add to Claude Desktop config file

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

💡 Bun を使う場合は npx を bunx に置き換えるだけでOK:

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

3. Restart Claude Desktop

That's it! Ask Claude to "say hello" and it will speak!

Quick Start with Docker

You can run both the MCP server and VOICEVOX Engine with a single command using Docker Compose. No Node.js or VOICEVOX installation required.

1. Start the containers

This starts the VOICEVOX Engine and the MCP server (HTTP mode on port 3000).

2. Add to Claude Desktop config file (using mcp-remote)

3. Restart Claude Desktop

Limitations (Docker): The Docker container has no audio device, so the voicevox_speak tool (server-side playback) is disabled by default. Use voicevox_speak_player instead — it plays audio on the client side (in Claude Desktop) and works without any audio device on the server. See UI Audio Player for details.

MCP Tools

voicevox_speak — Text-to-Speech

The main feature callable from Claude.

Examples:

Configuration

VOICEVOX Settings

Playback Options

Restriction Settings

Restrict AI from specifying certain options.

Disable Tools

UI Player Settings

Server Settings

Command line arguments take priority over environment variables.

For remote connections:

Start Server:

Claude Desktop Config (using mcp-remote):

Per-Project Speaker Settings

With Claude Code, you can configure different default speakers per project using custom headers in .mcp.json:

Example

This allows each project to use a different voice character automatically.

Priority order:

1. Explicit speaker parameter in tool call (highest)

2. Project default from X-Voicevox-Speaker header

3. Global VOICEVOX_DEFAULT_SPEAKER setting (lowest)

Connecting from WSL to an MCP server running on Windows:

1. Get Windows Host IP from WSL

2. Start Server on Windows

Add the WSL gateway IP to MCP_ALLOWED_HOSTS to allow access from WSL:

Or with CLI arguments:

3. WSL Configuration (.mcp.json)

⚠️ Within WSL, localhost refers to WSL itself. Use the WSL gateway IP to access the Windows host.

Troubleshooting

1. Check if VOICEVOX Engine is running

2. Check platform-specific playback tools

• Check package installation: npm list -g @kajidog/mcp-tts-voicevox

• Verify JSON syntax in config file

• Restart the client

Package Structure

Setup

Commands

License

ISC