MCP Simple AivisSpeech

English | 日本語

Special Thanks
This project is based on mcp-simple-voicevox by @t09tanaka.
We deeply appreciate their excellent work in creating the original MCP server for VOICEVOX, which served as the foundation for this AivisSpeech adaptation.

A Model Context Protocol (MCP) server for seamless integration with AivisSpeech text-to-speech engine. This project enables AI assistants and applications to convert text to natural-sounding Japanese speech with customizable voice parameters.

Features

• Text-to-Speech Conversion - High-quality Japanese speech synthesis using AivisSpeech
• Multiple Voice Characters - Support for various speakers and voice styles (default: Anneli )
• Configurable Parameters - Adjust speed, pitch, volume, and intonation
• Cross-Platform Audio - Automatic audio playback on macOS, Windows, and Linux
• Task Notifications - Voice notifications for process completion
• Easy Integration - Simple MCP protocol for AI assistant integration
• Engine Status Monitoring - Real-time status checking of AivisSpeech engine
• Smart Error Handling - Helpful error messages with speaker suggestions

Prerequisites

• Node.js - Version 18.0.0 or higher
• AivisSpeech Engine - Running on http://127.0.0.1:10101 (default port)
• Audio System - System audio capabilities for playback

MCP Simple AivisSpeech Configuration

Using Claude Code

When using Claude Code, start the MCP server manually before using it.

Using npx ensures you always get the latest version automatically. No manual updates needed.

1. Start the AivisSpeech MCP server manually in a separate terminal from the one where you're using Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

1. Register the MCP server with Claude Code

claude mcp add aivisspeech -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

By default, the server is added to the local scope (current project only). To make it available across all projects, use the -s user option:

claude mcp add aivisspeech -s user -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

You can also add voice notifications to your CLAUDE.md file to automate task completion notifications:

## Task Completion Behavior
- When all tasks are completed, always use the aivisspeech mcp tool to announce "Tasks completed" via voice
- When user input or decision is needed, use the aivisspeech mcp tool to announce "Awaiting your decision" via voice

### Notification Timings
- When asking the user a question
- When all tasks are completed
- When errors or issues occur

1. Verify the tools are recognized

claude mcp list

# Or launch Claude Code and use
/mcp

If aivisspeech is displayed, the setup was successful.

Tip: Claude Code doesn't auto-execute commands for safety. If you forget to start the server, the tools won't appear. During development, keep the above npx command running in a terminal, or use process managers like pm2 or systemd --user for persistent operation.

Using Claude Desktop

For manual configuration with Claude Desktop, you can simply add the following configuration:

Using npx ensures you always get the latest version automatically. No manual updates needed.

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

AivisSpeech Engine Setup

Before using this MCP server, complete these setup steps to ensure AivisSpeech is running locally.

1. Download AivisSpeech from https://aivis-project.com/
2. Launch AivisSpeech on your local machine
3. The engine will start on the default port 10101
4. Verify the engine is running by visiting http://127.0.0.1:10101/docs

Other Usage Methods

For Local Development

# Run the MCP server
npm start

# For development with hot reload
npm run dev

# Check if everything is working
npm test

For cloning the repository, installing dependencies, and building:

# Clone repository
git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git
cd mcp-simple-aivisspeech

# Install dependencies
npm install

# Build the project
npm run build

Available Tools

speak

Convert text to speech and play audio with customizable voice parameters.

This tool accepts several configuration parameters, including the following options:

• text (required): Text to convert to speech
• speaker (optional): Speaker/voice ID (default: 888753760 - Anneli )
• speedScale (optional): Speech speed multiplier (0.5-2.0, default: 1.0)
• pitchScale (optional): Pitch adjustment (-0.15-0.15, default: 0.0)
• volumeScale (optional): Volume level (0.0-2.0, default: 1.0)
• playAudio (optional): Whether to play the generated audio (default: true)

Example usage:

{
  "text": "世界",
  "speaker": 888753760,
  "speedScale": 1.2,
  "pitchScale": 0.05,
  "volumeScale": 1.5
}

get_speakers

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

This function returns: List of speakers with their IDs, names, and available voice styles.

notify_completion

Play a voice notification when tasks are completed.

This tool accepts several configuration parameters, including the following options:

• message (optional): Completion message to announce (default: "処理完了")
• speaker (optional): Speaker ID for the notification voice (default: 888753760 - Anneli )

Example usage:

{
  "message": "処理完了",
  "speaker": 888753760
}

check_engine_status

Check the cu…