AivisSpeech

Un servidor para la generación de texto a voz utilizando el motor AivisSpeech.

Documentación

MCP Simple AivisSpeech

Project Logo

🙏 Agradecimientos especiales
Este proyecto está basado en mcp-simple-voicevox de @t09tanaka.
Apreciamos profundamente su excelente trabajo al crear el servidor MCP original para VOICEVOX, que sirvió como base para esta adaptación de AivisSpeech.

Un servidor de Model Context Protocol (MCP) para una integración perfecta con el motor de texto a voz AivisSpeech. Este proyecto permite a los asistentes de IA y aplicaciones convertir texto en voz japonesa de sonido natural con parámetros de voz personalizables.

✨ Características

Conversión de texto a voz: síntesis de voz japonesa de alta calidad usando AivisSpeech
Múltiples personajes de voz: soporte para varios hablantes y estilos de voz (predeterminado: Anneli ノーマル)
Parámetros configurables: ajusta velocidad, tono, volumen y entonación
Audio multiplataforma: reproducción automática de audio en macOS, Windows y Linux
Notificaciones de tareas: notificaciones de voz para la finalización de procesos
Integración fácil: protocolo MCP simple para la integración con asistentes de IA
Monitoreo del estado del motor: verificación en tiempo real del estado del motor AivisSpeech
Manejo inteligente de errores: mensajes de error útiles con sugerencias de hablantes

📋 Requisitos previos

Node.js: versión 18.0.0 o superior
Motor AivisSpeech: ejecutándose en http://127.0.0.1:10101 (puerto predeterminado)
Sistema de audio: capacidades de audio del sistema para la reproducción

Configuración de MCP Simple AivisSpeech

Usando Claude Code

Al usar Claude Code, inicie el servidor MCP manualmente antes de usarlo.

Usar npx garantiza que siempre obtenga la última versión automáticamente. No se necesitan actualizaciones manuales.

Inicie el servidor MCP de AivisSpeech manualmente en una terminal separada de la que está usando para Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

Registre el servidor MCP con Claude Code

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

De forma predeterminada, el servidor se agrega al ámbito local (solo el proyecto actual). Para que esté disponible en todos los proyectos, use la opción -s user:

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

También puede agregar notificaciones de voz a su archivo CLAUDE.md para automatizar las notificaciones de finalización de tareas:

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

Verifique que las herramientas sean reconocidas

claude mcp list

# Or launch Claude Code and use
/mcp

Si se muestra aivisspeech, la configuración fue exitosa.

💡 Consejo: Claude Code no ejecuta comandos automáticamente por seguridad. Si olvida iniciar el servidor, las herramientas no aparecerán. Durante el desarrollo, mantenga el comando npx anterior ejecutándose en una terminal, o use administradores de procesos como pm2 o systemd --user para una operación persistente.

Usando Claude Desktop

Para la configuración manual con Claude Desktop, simplemente puede agregar la siguiente configuración:

Usar npx garantiza que siempre obtenga la última versión automáticamente. No se necesitan actualizaciones manuales.

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

⚙️ Configuración del motor AivisSpeech

Antes de usar este servidor MCP, complete estos pasos de configuración para asegurarse de que AivisSpeech se esté ejecutando localmente.

Descargue AivisSpeech desde https://aivis-project.com/
Inicie AivisSpeech en su máquina local
El motor se iniciará en el puerto predeterminado 10101
Verifique que el motor esté ejecutándose visitando http://127.0.0.1:10101/docs

📖 Otros métodos de uso

Para desarrollo local

# Run the MCP server
npm start

# For development with hot reload
npm run dev

# Check if everything is working
npm test

Para clonar el repositorio, instalar dependencias y compilar:

# 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

🛠️ Herramientas disponibles

🎤 `speak`

Convierte texto a voz y reproduce audio con parámetros de voz personalizables.

Esta herramienta acepta varios parámetros de configuración, incluyendo las siguientes opciones:

text (obligatorio): texto a convertir en voz
speaker (opcional): ID del hablante/voz (predeterminado: 888753760 - Anneli ノーマル)
speedScale (opcional): multiplicador de velocidad del habla (0.5-2.0, predeterminado: 1.0)
pitchScale (opcional): ajuste de tono (-0.15-0.15, predeterminado: 0.0)
volumeScale (opcional): nivel de volumen (0.0-2.0, predeterminado: 1.0)
playAudio (opcional): si se debe reproducir el audio generado (predeterminado: true)

Ejemplo de uso:

{
  "text": "こんにちは、世界！",
  "speaker": 888753760,
  "speedScale": 1.2,
  "pitchScale": 0.05,
  "volumeScale": 1.5
}

👥 `get_speakers`

Recupera una lista de todos los personajes de voz disponibles y sus estilos.

Esta función devuelve: lista de hablantes con sus IDs, nombres y estilos de voz disponibles.

🔔 `notify_completion`

Reproduce una notificación de voz cuando se completan las tareas.

Esta herramienta acepta varios parámetros de configuración, incluyendo las siguientes opciones:

message (opcional): mensaje de finalización para anunciar (predeterminado: "処理が完了しました")
speaker (opcional): ID del hablante para la voz de notificación (predeterminado: 888753760 - Anneli ノーマル)

Ejemplo de uso:

{
  "message": "データ処理が完了しました",
  "speaker": 888753760
}

📊 `check_engine_status`

Verifica el estado actual y la versión del motor AivisSpeech.

Esta función devuelve: estado del motor, información de versión y detalles de conectividad.

🖥️ Soporte de plataformas

Sistemas de reproducción de audio

Plataforma	Comando de audio	Requisitos
macOS	`afplay`	Integrado (sin configuración adicional)
Windows	PowerShell Media.SoundPlayer	Windows PowerShell
Linux	`aplay`	Utilidades ALSA (`sudo apt install alsa-utils`)

Entornos probados

macOS 12+ (Intel y Apple Silicon)
Windows 10/11
Ubuntu 20.04+
Node.js 18.x, 20.x, 21.x

🧪 Desarrollo

Scripts disponibles

# Development & Building
npm run dev          # Run with hot reload (tsx)
npm run build        # Compile TypeScript to dist/
npm start           # Run compiled server

# Code Quality
npm run lint        # Run ESLint
npm run test        # Run Vitest tests (single run)
npm run test:watch  # Run tests in watch mode
npm run test:ui     # Run tests with UI
npm run test:coverage # Run tests with coverage

# Utilities
npm run clean       # Clean dist/ directory

Uso local vs NPX

Al usar clientes MCP en producción, use npx @shinshin86/mcp-simple-aivisspeech@latest en su configuración MCP. No se requiere configuración local y siempre obtiene la última versión.

Para desarrollo, clone el repositorio y use npm run dev para recarga en caliente, o npm run build && npm start para probar compilaciones de producción.

Arquitectura del proyecto

mcp-simple-aivisspeech/
├── src/
│   ├── index.ts                  # MCP server & tool handlers
│   └── aivisspeech-client.ts     # AivisSpeech API client
├── tests/
│   └── aivisspeech-client.test.ts # Unit tests
├── dist/                         # Compiled output
├── docs/                         # Documentation
└── config files                  # TS, ESLint, Vitest configs

Arquitectura del cliente API

La clase AivisSpeechClient ofrece funcionalidad integral, proporcionando varias capacidades clave:

Cliente HTTP: comunicación API basada en Axios
Manejo de errores: captura y reporte integral de errores
Seguridad de tipos: interfaces completas de TypeScript para todas las respuestas de API
Gestión de conexiones: verificaciones de salud y monitoreo de estado

Agregar nuevas características

Nueva herramienta: agregue el manejador en src/index.ts CallToolRequestSchema
Métodos API: extienda la clase AivisSpeechClient
Tipos: actualice las interfaces en aivisspeech-client.ts
Pruebas: agregue los casos de prueba correspondientes

🔧 Solución de problemas

Problemas comunes

Motor AivisSpeech no encontrado

Error: Failed to get version: connect ECONNREFUSED 127.0.0.1:10101

Considere estos enfoques de solución de problemas para resolver este problema: asegúrese de que el motor AivisSpeech se esté ejecutando en el puerto correcto.

La reproducción de audio falla

Error: Audio player exited with code 1

Considere estos enfoques de solución de problemas para resolver este problema:

macOS: verifique si afplay está disponible
Linux: instale las utilidades ALSA (sudo apt install alsa-utils)
Windows: asegúrese de que la política de ejecución de PowerShell permita scripts

Permiso denegado

Error: spawn afplay EACCES

Considere estos enfoques de solución de problemas para resolver este problema: verifique los permisos de archivos y la configuración de audio del sistema.

Modo de depuración

Para habilitar el registro detallado, ejecute el siguiente comando:

DEBUG=mcp-aivisspeech npm run dev

📄 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0; consulte el archivo LICENSE para más detalles.

🤝 Contribuciones

Agradecemos las contribuciones de la comunidad. Los contribuyentes pueden comenzar completando estos pasos esenciales:

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Confirme sus cambios (git commit -m 'Add amazing feature')
Empuje a la rama (git push origin feature/amazing-feature)
Abra una solicitud de extracción

Pautas de desarrollo

Siga las configuraciones existentes de TypeScript/ESLint
Agregue pruebas para nuevas funcionalidades
Actualice la documentación para cambios de API
Asegure la compatibilidad multiplataforma

🙏 Agradecimientos

Proyecto AivisSpeech por el excelente motor TTS
Model Context Protocol por el marco de integración
VOICEVOX MCP por la inspiración y referencia

📞 Soporte

Problemas: GitHub Issues
Discusiones: GitHub Discussions
Documentación: AivisSpeech API Docs

Hecho con ❤️ para la comunidad japonesa de TTS