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 (ChatGPT / Claude Desktop / Claude Web etc.)
• 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
• Segment editing — Adjust speed, volume, intonation, pause length, and pre/post silence per segment
• Accent phrase editing — Edit accent positions and mora pitch directly in the UI
• Add / delete / reorder segments — Drag-and-drop track reordering; add new segments inline
• WAV export — Save all tracks as numbered WAV files and open the output folder automatically
• User dictionary manager — Add, edit, and delete VOICEVOX user dictionary words with preview playback
• Cross-session state restore — Player state is persisted on the server; reopening the chat restores previous tracks

Export behavior by environment:

• Save and open always exports WAV files. If opening the file explorer is not supported, export still succeeds and the save path is shown in the UI.
• Choose output folder uses a native directory picker on Windows/macOS. On unsupported environments, this action falls back to the default export directory.

Supported Clients

Note: speak_player requires a host that supports MCP Apps. In hosts without MCP Apps support, the tool is not available and speak (server-side playback) can be used instead.

Player MCP Tools

Quick Start

Requirements

• Node.js 24.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)

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

{
  "mcpServers": {
    "tts-mcp": {
      "command": "npx",
      "args": ["-y", "@kajidog/mcp-tts-voicevox"]
    }
  }
}

💡 If using Bun, just replace npx with bunx:

"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

docker compose up -d

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

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

{
  "mcpServers": {
    "tts-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

3. Restart Claude Desktop

Security (Docker): docker-compose.yml publishes port 3000 without authentication. MCP_ALLOWED_HOSTS is not a defense here — non-browser clients can send any Host header they like — so anyone who can reach the port can use the server. Set MCP_API_KEY (and send it as X-API-Key), or keep the port bound to a trusted network / localhost only. Consider also setting VOICEVOX_ALLOWED_OUTPUT_DIRS to limit where file-writing tools may write.

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.

immediate / waitForStart / waitForEnd disappear from the tool schema when the matching --restrict-* option is set.

Examples:

// Simple text
{ "text": "Hello" }

// Specify speaker
{ "text": "Hello", "speaker": 3 }

// Different speakers per segment
{ "text": "1:Hello\n3:Nice weather today" }

// Wait for completion (synchronous processing)
{ "text": "Wait for this to finish before continuing", "waitForEnd": true }

// Control the accent with inline notation (`,` separates phrases, `[` marks the accent)
{ "text": "こんにちは世界", "phrases": "コン[ニ]チワ,セ[カ]イ" }

Inline Accent Notation

phrases (and the pronunciation field of the user dictionary tools) accepts katakana with an inline accent marker:

• , separates accent phrases — コン[ニ]チワ,セ[カ]イ
• [ marks where the pitch drops after; コン[ニ]チワ means the accent falls on ニ
• Omitting the brackets for a phrase keeps VOICEVOX’s own accent estimation for it

text stays required even when phrases is given — pass the plain text there and the notation is what gets spoken.

voicevox_get_accent_phrases returns the same notation for a given text, so you can read the estimated accent, tweak the bracket, and feed it back into phrases.

---

Configuration

---

Troubleshooting

---

Package Structure

---

---

License

ISC