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.

Un servidor Model Context Protocol (MCP) per a una integració sense soroll amb el motor TTS AivisSpeech. Aquest projecte permet als assistents IA i aplicacions convertir text en parla japonesa natural amb paràmetres de veu personalitzables.

✨ Features

• Text-to-Speech Conversion - Alta qualitat de síntesi de parla japonesa amb AivisSpeech
• Multiple Voice Characters - Suport per a diversos oradors i estils de veu (per defecte: Anneli ノーマル)
• Configurable Parameters - Ajusta velocitat, pitch, volum i intonació
• Cross-Platform Audio - Reproducció automàtica d’àudio a macOS, Windows i Linux
• Task Notifications - Notificacions de veu quan es completen tasques
• Easy Integration - Protocol MCP senzill per a la integració amb assistents IA
• Engine Status Monitoring - Comprovació en temps real del estat de l’engine AivisSpeech
• Smart Error Handling - Missatges d’error útils amb suggeriments de oradors

📋 Prerequisites

• Node.js - Versió 18.0.0 o superior
• AivisSpeech Engine - Funcionant a http://127.0.0.1:10101 (port per defecte)
• Audio System - Capacitat d’àudio del sistema per a reproducció

MCP Simple AivisSpeech Configuration

Using Claude Code

Quan utilitzes Claude Code, inicia el servidor MCP manualment abans d’utilitzar-lo.

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

1. Inicia el servidor MCP AivisSpeech manualment en un terminal separat del que utilitzes per a Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

2. Registra el servidor MCP amb Claude Code

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

Per defecte, el servidor s’afegeix a l’àmbit local (només el projecte actual). Per fer-lo disponible a tots els projectes, utilitza l’opció -s user:

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

També pots afegir notificacions de veu al teu fitxer CLAUDE.md per automatitzar les notificacions de finalització de tasques:

## 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. Verifica que les eines siguin reconegudes

claude mcp list

# Or launch Claude Code and use
/mcp

Si aivisspeech apareix, la configuració ha estat exitosa.

💡 Tip: Claude Code no executa automàticament els comandaments per seguretat. Si oblides iniciar el servidor, les eines no apareixeran. Durant el desenvolupament, mantén el comandament npx en execució en un terminal, o utilitza gestors de processos com pm2 o systemd --user per a operacions persistents.

Using Claude Desktop

Per a una configuració manual amb Claude Desktop, pots afegir la següent configuració:

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

Abans d’utilitzar aquest servidor MCP, completa aquests passos per assegurar que AivisSpeech s’estigui executant localment.

1. Descarrega AivisSpeech des de https://aivis-project.com/
2. Inicia AivisSpeech a la teva màquina local
3. L’engine s’inicia al port per defecte 10101
4. Verifica que l’engine està funcionant visitant 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

Per clonar el repositori, instal·lar dependències i construir:

# 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

Converteix text a veu i reproduïx l’àudio amb paràmetres de veu personalitzables.

Aquesta eina accepta diversos paràmetres de configuració, incloent les opcions següents:

• text(required): Text a convertir a veu
• speaker(optional): ID d’orador/veu (per defecte: 888753760 - Anneli ノーマル)
• speedScale(optional): Multiplicador de velocitat de veu (0.5-2.0, per defecte: 1.0)
• pitchScale(optional): Ajust de pitch (-0.15 龙-0.15, per defecte: 0.0)
• volumeScale(optional): Ajust de volum (0.0-1.0, per defecte: 1.0)

Exemple:

{
  "text": "Hola, món!",
  "speaker": 888753760,
  "speedScale": 1.2,
  "pitchScale": 0.1,
  "volumeScale": 0.9
}

🔍 get_speakers

Obtén la llista d’oradors disponibles i els seus estils.

🔔 notify_completion

Notifica per veu quan una tasca es completi.

🔍 check_engine_status

Comprova l’estat en temps real de l’engine AivisSpeech.

Platform Support

Tested Environments

• Node.js 18.x, 20.x
• AivisSpeech 1.0.0 (port 10101)
• macOS 12+, Windows 10+, Ubuntu 20.04+
• Sistema d’àudio funcional (ALSA, CoreAudio, WASAPI)

Development

Scripts

• npm run dev - Servei amb hot reload
• npm run build - Construcció del projecte
• npm start - Executa el servidor MCP
• npm test - Tests unitaris amb Vitest
• npm run lint - Lint amb ESLint

Local vs NPX Usage

Per a desenvolupament local, utilitza npm run dev i npm run build. Per a l’ús en entorns de producció, executa el servidor amb npx @shinshin86/mcp-simple-aivisspeech@latest i registra’l amb claude mcp add.

Project Architecture

mcp-simple-aivisspeech/ ├─ src/ │ ├─ server.ts # Lògica del servidor MCP │ ├─ tools/ │ │ ├─ speak.ts # Eina speak │ │ ├─ get_speakers.ts # Eina get_speakers │ │ ├─ notify_completion.ts # Eina notify_completion │ │ └─ check_engine_status.ts # Eina check_engine