MCP Simple AivisSpeech

This MCP server lets you connect AivisSpeech text-to-speech with your AI assistants and apps using the MCP protocol. You can convert Japanese text to natural-sounding speech, choose from multiple voices, adjust delivery properties like speed and pitch, and receive voice notifications when tasks complete. It works across macOS, Windows, and Linux and supports real-time engine status checks and helpful error messages to guide you.

How to use

You use an MCP client to request speech synthesis from AivisSpeech through this MCP server. Start the MCP server and register it with your MCP client so you can convert text to speech, retrieve available speakers, and play audio directly in your applications. You can enable voice notifications for task progress and completion, and you can query the engine status to ensure the AivisSpeech backend is healthy.

How to install

Prerequisites you need before installing and running: Node.js version 18.0.0 or newer, and the AivisSpeech engine running locally on http://127.0.0.1:10101.

# Start the AivisSpeech MCP server manually (in a separate terminal)
npx @shinshin86/mcp-simple-aivisspeech@latest

# If you are configuring Claude Code, register the MCP server with Claude
claude mcp add aivisspeech -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

# To make it available across all projects, specify global scope
claude mcp add aivisspeech -s user -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

For manual configuration with Claude Desktop, you can add the MCP server configuration like this in your MCP settings:

{
  "mcpServers": {
    "aivisspeech": {
      "command": "npx",
      "args": ["@shinshin86/mcp-simple-aivisspeech@latest"],
      "env": {
        "AIVISSPEECH_URL": "http://127.0.0.1:10101"
      }
    }
  }
}

Additional setup details

The AivisSpeech engine runs on port 10101 by default. Ensure it is started and reachable at http://127.0.0.1:10101/docs to verify the API and capabilities.

Available tools let you perform speech synthesis, list speakers, receive completion notifications, and check engine status. The default speaker often used is Anneli ノーマル, but you can select other voices and adjust delivery characteristics as needed.

Notes on usage and features

• Text-to-Speech Conversion lets you produce high-quality Japanese speech with customizable voice parameters such as speed, pitch, and volume.

• Multiple Voice Characters provide a range of speakers and styles for different contexts.

• Configurable Parameters include speedScale, pitchScale, and volumeScale to tailor voice output for your needs.

• Audio playback works across macOS, Windows, and Linux, using the system’s native audio facilities.

• Engine Status Monitoring lets you verify that AivisSpeech is running and reachable.

• Smart Error Handling provides actionable messages with speaker suggestions when something goes wrong.

Troubleshooting and platform notes

If the engine cannot be reached, verify that AivisSpeech is running on port 10101 and that the endpoint URL is accessible from your machine.

If audio playback fails, ensure your system audio commands (afplay on macOS, ALSA on Linux, and PowerShell-based playback on Windows) are available and permitted.

For permission-related errors, check file permissions and system audio settings to allow the MCP server to spawn and play audio.

Available tools

speak

Convert text to speech and play audio with adjustable speaker, speedScale, pitchScale, and volumeScale.

get_speakers

Return a list of all available voice characters and their styles.

notify_completion

Play a voice notification when tasks are completed with optional message and speaker.

check_engine_status

Check the current status and version of the AivisSpeech engine.