# mcp-simple-aivisspeech
## 基本信息
- Slug: `shinshin86-mcp-simple-aivisspeech`
- Source: modelscope
- Publisher: @shinshin86/mcp-simple-aivisspeech
- Categories: text-to-speech / speech-processing / language-translation
- Hosted: No
- License: Apache License 2.0
- Source URL: https://www.modelscope.cn/mcp/servers/@shinshin86/mcp-simple-aivisspeech
## 简介
暂无描述。
## 安装提示

```bash
npx @shinshin86/mcp-simple-aivisspeech@latest
```

## MCP Server 详情

# MCP Simple AivisSpeech

![Project Logo](./images/mcp-simple-aivisspeech_logo.png)

[English](README.md) | [日本語](README.ja.md)

>  **Special Thanks**  
> This project is based on [mcp-simple-voicevox](https://github.com/t09tanaka/mcp-simple-voicevox) by [@t09tanaka](https://github.com/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

```bash
npx @shinshin86/mcp-simple-aivisspeech@latest
```

2. Register the MCP server with Claude Code

```bash
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:

```bash
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:

```md
## 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
```

3. Verify the tools are recognized

```bash
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.

```json
{
  "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/](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

```bash
# 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:

```bash
# 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:
```json
{
  "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:
```json
{
  "message": "処理完了",
  "speaker": 888753760
}
```

###  `check_engine_status`
Check the cu…