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:

ffplay -version

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

VOICEVOX Settings

Playback Options

Restriction Settings

Restrict AI from specifying certain options.

Disable Tools

# Disable individual tools
export VOICEVOX_DISABLED_TOOLS=speak_player,synthesize_file

# Disable a built-in group of tools
export VOICEVOX_DISABLED_GROUPS=player

# Combine groups and individual tools
export VOICEVOX_DISABLED_GROUPS=dictionary
export VOICEVOX_DISABLED_TOOLS=synthesize_file

Built-in groups for VOICEVOX_DISABLED_GROUPS / --disable-groups:

UI Player Settings

Server Settings

Command line arguments take priority over environment variables.

# Basic settings
npx @kajidog/mcp-tts-voicevox --url http://192.168.1.100:50021 --speaker 3 --speed 1.2

# HTTP mode
npx @kajidog/mcp-tts-voicevox --http --port 8080

# With restrictions
npx @kajidog/mcp-tts-voicevox --restrict-immediate --restrict-wait-for-end

# Disable individual tools
npx @kajidog/mcp-tts-voicevox --disable-tools speak_player,synthesize_file

# Disable a tool group
npx @kajidog/mcp-tts-voicevox --disable-groups player

You can use a JSON config file instead of (or in addition to) environment variables and CLI arguments. This is useful when you have many settings to configure.

Priority order: CLI args > Environment variables > Config file > Defaults

Generate a config file

npx @kajidog/mcp-tts-voicevox --init

This creates .voicevoxrc.json in the current directory with all default settings. Edit it as needed.

Use a custom config file path

npx @kajidog/mcp-tts-voicevox --config ./my-config.json

Or via environment variable:

VOICEVOX_CONFIG=./my-config.json npx @kajidog/mcp-tts-voicevox

Example .voicevoxrc.json

{
  "url": "http://192.168.1.50:50021",
  "speaker": 3,
  "speed": 1.2,
  "http": true,
  "port": 8080,
  "disable-tools": ["synthesize_file"],
  "disable-groups": ["dictionary"]
}

Keys can be written in kebab-case (use-streaming), camelCase (useStreaming), or internal key names (defaultSpeaker). If .voicevoxrc.json exists in the current directory, it is loaded automatically.

For remote connections:

Start Server:

# Linux/macOS
MCP_HTTP_MODE=true MCP_HTTP_PORT=3000 npx @kajidog/mcp-tts-voicevox

# Windows PowerShell
$env:MCP_HTTP_MODE='true'; $env:MCP_HTTP_PORT='3000'; npx @kajidog/mcp-tts-voicevox

Claude Desktop Config (using mcp-remote):

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

Per-Project Speaker Settings

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

Example .mcp.json:

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Voicevox-Speaker": "113",
        "X-API-Key": "your-api-key"
      }
    }
  }
}

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

# Method 1: From default gateway
ip route show | grep -oP 'default via \K[\d.]+'
# Usually in the format 172.x.x.1

# Method 2: From /etc/resolv.conf (WSL2)
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

2. Start Server on Windows

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

$env:MCP_HTTP_MODE='true'
$env:MCP_ALLOWED_HOSTS='localhost,127.0.0.1,172.29.176.1'
npx @kajidog/mcp-tts-voicevox

Or with CLI arguments:

npx @kajidog/mcp-tts-voicevox --http --allowed-hosts "localhost,127.0.0.1,172.29.176.1"

3. WSL Configuration (.mcp.json)

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://172.29.176.1:3000/mcp"
    }
  }
}

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

To use with ChatGPT, deploy the MCP server in HTTP mode to the cloud with access to a VOICEVOX Engine.

1. Deploy to the Cloud

Deploy with Docker to Render, Railway, etc. (Dockerfile included).

2. Set Up VOICEVOX Engine

Run VOICEVOX Engine locally and expose it via ngrok, or deploy it alongside the MCP server.

3. Configure Environment Variables

4. Add Connector in ChatGPT

Go to ChatGPT Settings → Connectors → Add MCP server URL (https://your-app.onrender.com/mcp).

The basic steps are the same as ChatGPT, but the VOICEVOX_PLAYER_DOMAIN value is different.

Claude Web requires ui.domain to be a hash-based dedicated domain. Compute it with the following command:

node -e "console.log(require('crypto').createHash('sha256').update('Your MCP server URL').digest('hex').slice(0,32)+'.claudemcpcontent.com')"

Example: If your MCP server URL is https://your-app.onrender.com/mcp:

node -e "console.log(require('crypto').createHash('sha256').update('https://your-app.onrender.com/mcp').digest('hex').slice(0,32)+'.claudemcpcontent.com')"
# Example output: 48fb73a6...claudemcpcontent.com

Set this output value as VOICEVOX_PLAYER_DOMAIN.

Note: Since ChatGPT and Claude Web require different VOICEVOX_PLAYER_DOMAIN values, a single instance cannot serve both clients simultaneously. Deploy separate instances for each, or switch the environment variable depending on your target client.

1. Check if VOICEVOX Engine is running

curl http://localhost:50021/speakers

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

Setup

git clone https://github.com/kajidog/mcp-tts-voicevox.git
cd mcp-tts-voicevox
pnpm install

Commands