home / mcp / vv mcp server

VV MCP Server

Provides VoiceVox MCP endpoints to synthesize speech, manage voices, and control playback for Claude Desktop and Claude Code.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "arrow2nd-vv-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@arrow2nd/vv-mcp"
      ],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_SPEED": "1.0",
        "DEFAULT_VOICE_ID": "47",
        "VV_MCP_STATE_DIR": "/tmp"
      }
    }
  }
}

You can run the VV MCP Server to access VOICEVOX through an MCP client like Claude Desktop or Claude Code. It lets you synthesize speech from text, manage voices, and control playback from your editor or app, enabling seamless text-to-speech workflows without leaving your development environment.

How to use

After you start the MCP server, you expose a local endpoint that Claude Desktop or Claude Code can connect to. The server provides a set of tools you can call to synthesize speech, list available voices, inspect and manage the playback queue, and handle session-specific voice assignments. You can request a voice, play back text, and inspect current usage across all sessions.

How to install

Prerequisites you need to meet before installing this MCP server are straightforward. You must have Node.js 18 or newer and VOICEVOX installed and running. Your operating system will determine which audio backend is used: macOS uses afplay, while Linux relies on pulseaudio-utils (paplay) with the appropriate package for your distribution.

Install the MCP server globally using npm if you want the easiest start and broad compatibility.

npm install -g @arrow2nd/vv-mcp

If you prefer to build from source, clone the repository, install dependencies, and build the project.

git clone https://github.com/arrow2nd/vv-mcp.git
cd vv-mcp
npm install
npm run build

Configuration and environment variables

You configure Claude Desktop or Claude Code to connect to the local MCP server. The server relies on environment variables to control its behavior, including the VOICEVOX API URL, the default voice, and the default speech rate.

If you installed via npm, you can enable the MCP with these settings in your Claude Desktop configuration.

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Essential environment variables

These environment variables are used by the MCP server. Include them in your runtime configuration if you follow the npm-based approach.

VOICEVOX_URL=http://localhost:50021
DEFAULT_VOICE_ID=47
DEFAULT_SPEED=1.0
VV_MCP_STATE_DIR=TEMP

Using the server with Claude Desktop or Claude Code

Once the server is running, you can start conversing with Claude Desktop or Claude Code. Use the available MCP tools to say text, list voices, check queue status, clear the queue, get voices in use, obtain a random unused voice, or get the session voice for the current session.

Notes on multi-instance usage

If you run multiple Claude instances, each instance can be assigned a different voice to avoid conflicts. The system shares state via a temporary directory to coordinate voice usage across processes.

Troubleshooting and tips

Ensure VOICEVOX is running and accessible at the configured VOICEVOX_URL. If voices do not appear or playback fails, verify the audio backend on your OS (afplay on macOS, paplay on Linux) and confirm the required PulseAudio utilities are installed.

지원 언어 및 도구 목록

This MCP supports commands to synthesize speech, manage voices, and inspect playback state. Common actions include saying text, listing voices, checking the queue, and querying session-bound voices.

Available tools

say

Synthesize the given text to speech and play it back asynchronously.

list_voices

Return the list of available voices for VOICEVOX.

get_queue_status

Retrieve the current playback queue status.

clear_queue

Clear all items from the playback queue.

get_voices_in_use

List voice IDs currently in use across all sessions.

get_random_unused_voice

Select a random voice that is not currently in use.

get_session_voice

Get the voice assigned to the current session.