MCP Simple AivisSpeech

Español | 日本語

🙏 Agradecimientos especiales
Este proyecto está basado en mcp-simple-voicevox de @t09tanaka.
Agradecemos profundamente su excelente trabajo en la creación del servidor MCP original para VOICEVOX, que sirvió de base para esta adaptación de AivisSpeech.

Un servidor MCP (Model Context Protocol) para una integración perfecta con el motor de conversión de texto a voz AivisSpeech. Este proyecto permite a los asistentes y aplicaciones de IA convertir texto en habla 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 utilizando AivisSpeech
• Múltiples caracteres de voz - Soporte para varios hablantes y estilos de voz (por defecto: Anneli ノーマル)
• Parámetros configurables: ajuste la velocidad, el tono, el volumen y la 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
• Fácil integración - Protocolo MCP sencillo para la integración del asistente de IA
• Monitorización del estado del motor - Comprobación en tiempo real del estado del motor AivisSpeech
• Manejo inteligente de errores - Mensajes de error útiles con sugerencias del hablante

📋 Requisitos previos

• Node.js - Versión 18.0.0 o superior
• Motor AivisSpeech - Ejecutándose en http://127.0.0.1:10101 (puerto por defecto)
• Sistema de audio - Capacidades de audio del sistema para la reproducción

Configuración MCP Simple AivisSpeech

Uso de Claude Code

Cuando utilice Claude Code, inicie el servidor MCP manualmente antes de utilizarlo.

El uso de npx garantiza que siempre obtendrá la última versión de forma automática. No se necesitan actualizaciones manuales.

1. Inicie manualmente el servidor MCP de AivisSpeech en un terminal distinto del que está utilizando Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

2. 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

Por defecto, el servidor se añade al ámbito local (sólo al proyecto actual). Para que esté disponible en todos los proyectos, utilice la opción -s usuario:

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

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

## Comportamiento de la finalización de tareas - Cuando todas las tareas estén completadas, utilice siempre la herramienta mcp aivisspeech para anunciar "Tareas completadas" mediante voz - Cuando se necesite la opinión o decisión del usuario, utilice la herramienta mcp aivisspeech para anunciar "Esperando su decisión" mediante voz ### Momentos de notificación - Cuando se le haga una pregunta al usuario - Cuando todas las tareas estén completadas - Cuando se produzcan errores o problemas

3. Verificar que las herramientas son reconocidas

claude mcp list # O inicie Claude Code y utilice /mcp

Si aparece aivisspeech, la configuración se ha realizado correctamente.

💡 Consejo: Claude Code no auto-ejecuta comandos por seguridad. Si olvida iniciar el servidor, las herramientas no aparecerán. Durante el desarrollo, mantenga el comando npx anterior ejecutándose en un terminal, o utilice gestores de procesos como pm2 o systemd --user para un funcionamiento persistente.

Uso de Claude Desktop

Para la configuración manual con Claude Desktop, puedes simplemente añadir la siguiente configuración:

Usando npx te aseguras de obtener siempre 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 utilizar este servidor MCP, complete estos pasos de configuración para asegurarse de que AivisSpeech se ejecuta localmente.

1. Descargue AivisSpeech de https://aivis-project.com/
2. Inicie AivisSpeech en su equipo local
3. El motor se iniciará en el puerto predeterminado 10101
4. Compruebe que el motor se está ejecutando visitando http://127.0.0.1:10101/docs

otros métodos de uso

Para desarrollo local

# Ejecutar el servidor MCP npm start # Para desarrollo con recarga en caliente npm run dev # Comprobar si todo funciona npm test

Para clonar el repositorio, instalar dependencias y construir:

# Clonar repositorio git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git cd mcp-simple-aivisspeech # Instalar dependencias npm install # Construir el proyecto npm run build

🛠️ Herramientas disponibles

🎤 hablar

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
• altavoz(opcional): ID del locutor/voz (por defecto: 888753760 - Anneli ノーマル)
• speedScale(opcional): Multiplicador de la velocidad del habla(0,5-2,0; por defecto: 1,0)
• pitchScale(opcional): Ajuste del tono(-0,15-0,15, por defecto: 0,0)
• volumeScale(opcional): Nivel de volumen(0,0-2,0, por defecto: 1,0)
• playAudio(opcional): Si reproducir el audio generado (por defecto: true)

Ejemplo de uso:

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

👥 get_speakers

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

Esta función devuelve: Lista de altavoces 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:

• mensaje(opcional): Mensaje de finalización a anunciar (por defecto: "処理が完了しました")
• altavoz(opcional): ID del altavoz para la voz de notificación (por defecto: 888753760 - Anneli ノーマル)

Ejemplo de uso:

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

📊 comprobar_estado_del_motor

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

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

🖥️ Soporte de plataformas

Sistemas de reproducción de audio

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

# Desarrollo y construcción npm run dev # Ejecutar con recarga en caliente (tsx) npm run build # Compilar TypeScript a dist/ npm start # Ejecutar servidor compilado # Calidad del código npm run lint # Ejecutar ESLint npm run test # Ejecutar pruebas Vitest (ejecución única) npm run test:watch # Ejecutar pruebas en modo watch npm run test:ui # Ejecutar pruebas con UI npm run test:coverage # Ejecutar pruebas con cobertura # Utilidades npm run clean # Limpiar dist/ directorio

Uso local vs NPX

Cuando utilice clientes MCP en producción, utilice npx @shinshin86/mcp-simple-aivisspeech@latest en su configuración MCP. No se requiere configuración local y siempre obtendrá la última versión.

Para desarrollo, clona el repositorio y usa npmrundev para recargar en caliente, o npm run build && npm start para probar las 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 # Pruebas unitarias ├── dist/ # Salida compilada ├── docs/ # Documentación └── archivos config # TS, ESLint, Vitest configs

Arquitectura del cliente API

La clase AivisSpeechClient ofrece una funcionalidad completa, proporcionando varias capacidades clave:

• Cliente HTTP - Comunicación API basada en Axios
• Gestión de errores - Detección e informe de errores completos
• Type Safety - Interfaces TypeScript completas para todas las respuestas de la API
• Gestión de conexiones: comprobaciones de estado y supervisión del estado

Adición de nuevas funciones

1. Nueva herramienta: Añadir manejador en src/index.tsCallToolRequestSchema
2. Métodos API: Extensión de la clase AivisSpeechClient
3. Tipos: Actualizar interfaces en aivisspeech-client.ts
4. Pruebas: Añadir los casos de prueba correspondientes

🔧 Solución de problemas

Problemas comunes

No se encuentra el motor AivisSpeech

Error: Error al obtener la versión: connect ECONNREFUSED 127.0.0.1:10101

Tenga en cuenta estos métodos de solución de problemas para resolver este problema: Asegúrese de que AivisSpeech Engine se ejecuta en el puerto correcto.

La reproducción de audio falla

Error: El reproductor de audio sale con el código 1

Considere estos métodos de solución de problemas para resolver este problema:

• macOS - Compruebe 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 permite scripts

Permiso denegado

Error: spawn afplay EACCES

Considere estos métodos de solución de problemas para resolver este problema: Compruebe los permisos de archivo y la configuración de audio del sistema.

Modo de depuración

Para activar el registro detallado, ejecute el siguiente comando:

DEBUG=mcp-aivisspeech npm run dev

📄 Licencia

Este proyecto está licenciado bajo la Apache License 2.0 - ver el archivo LICENSE para más detalles.

🤝 Contribución

Agradecemos las contribuciones de la comunidad. Los colaboradores pueden empezar completando estos pasos esenciales:

1. Fork el repositorio
2. Crea una rama(git checkout -b feature/amazing-feature)
3. Confirme sus cambios(git commit -m 'Añadir característica asombrosa')
4. Empuja a la rama(git push origin feature/amazing-feature)
5. Abrir una Pull Request

Pautas de desarrollo

• Sigue las configuraciones TypeScript/ESLint existentes
• Añadir pruebas para la nueva funcionalidad
• Actualizar la documentación para los cambios en la API
• Asegurar la compatibilidad entre plataformas

🙏 Agradecimientos

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

📞 Soporte

• Temas - GitHub Temas
• Debates - Debates en GitHub
• Documentación - AivisSpeech API Docs

Hecho con ❤️ para la comunidad TTS japonesa