ElevenLabs MCP Enhanced

Generación de texto a voz con funciones de historial de conversaciones utilizando la API de ElevenLabs.

Documentación

ElevenLabs MCP Enhanced

Fork mejorado del servidor MCP oficial de ElevenLabs con funciones adicionales de IA conversacional, incluyendo recuperación de historial de conversaciones y transcripciones.

Esta versión mejorada está desarrollada y mantenida por Boris Djordjevic y el equipo de 199 Longevity.

🚀 Novedades en Este Fork

Esta versión mejorada añade funciones críticas de IA conversacional que faltaban en el original:

🤖 Mejoras Amigables para IA (v1.0.0)

✅ API oficial v3: Ahora utiliza los endpoints oficiales de ElevenLabs: ¡no se necesita proxy!
🎯 Valores Predeterminados de Voz Inteligentes: search_voices() ahora devuelve voces comunes y funcionales al instante
📚 Mensajes de Error Educativos: Los errores guían a los agentes de IA hacia el éxito con ejemplos
💡 Guía Clara de Herramientas: No más confusión entre herramientas de un solo hablante vs. múltiples hablantes
🎤 IDs de Voz v3 Precisos: Las 20 voces optimizadas para v3 ahora tienen IDs y descripciones correctos
🏯 División Automática de Diálogos Largos: Divide automáticamente diálogos de más de 3000 caracteres en múltiples archivos
🎯 Ajuste Automático de Estabilidad: Los valores de estabilidad no válidos se redondean automáticamente a la opción válida más cercana (0.0, 0.5, 1.0)
🏷️ Simplificación Inteligente de Etiquetas: Las etiquetas complejas se convierten automáticamente a etiquetas v3 válidas para mejor calidad
⏱️ Tiempos de Espera Dinámicos: Previene tiempos de espera en diálogos complejos calculando tiempos de espera apropiados

🆕 Soporte del Modelo v3 de ElevenLabs (Oficial)

🎭 Expresividad Mejorada: Usa el modelo v3 oficial con el parámetro model="v3"
🎤 Etiquetas de Audio: Añade emociones y efectos de sonido como [thoughtful], [crying], [laughing], [piano]
👥 Diálogo Multi-Hablante: Genera conversaciones naturales entre múltiples hablantes
✨ Mejora de Diálogo: Mejora automáticamente tu diálogo con formato y etiquetas apropiados
🌍 Más de 70 Idiomas: v3 soporta síntesis multilingüe con control emocional
✅ API Oficial: Ahora utiliza el endpoint oficial de texto-a-diálogo de ElevenLabs

🎙️ Funciones de IA Conversacional

Historial de Conversaciones: Recupera detalles completos de conversaciones, incluyendo transcripciones
📝 Acceso a Transcripciones: Obtén transcripciones de conversaciones en múltiples formatos (texto plano, marcas de tiempo, JSON)
⏳ Monitoreo en Tiempo Real: Espera a que las conversaciones en curso se completen y recupera los resultados
🔍 Búsqueda de Conversaciones: Lista y filtra conversaciones por agente, estado y más
🎨 Formato Mejorado: Formato consistente en todas las operaciones de listado

Acerca de

Este es un fork mejorado del servidor Model Context Protocol (MCP) oficial de ElevenLabs que permite la interacción con potentes APIs de Texto a Voz y procesamiento de audio. Este servidor permite que clientes MCP como Claude Desktop, Cursor, Windsurf, OpenAI Agents y otros generen voz, clonen voces, transcriban audio, gestionen agentes de IA conversacional y ahora recuperen historial de conversaciones.

🚀 Instalación Rápida

Instalación Cero (Recomendada)

¡No se requiere instalación! Solo usa npx:

npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

Instalación Global

Instala una vez, úsalo en todas partes:

npm install -g elevenlabs-mcp-enhanced
elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

Variable de Entorno

Configura tu clave de API una vez:

export ELEVENLABS_API_KEY="your-api-key"
npx elevenlabs-mcp-enhanced

📋 Requisitos

Node.js 16+ (para npm/npx)
Python 3.11+ (gestionado automáticamente por el paquete npm)
Clave de API de ElevenLabs - Obtén una en elevenlabs.io

Inicio Rápido con Claude Desktop

Opción 1: Usando npm/npx (Recomendado: ¡No se requiere instalación!)

Obtén tu clave de API en ElevenLabs. Hay un nivel gratuito con 10k créditos al mes.
Ve a Claude > Configuración > Desarrollador > Editar Configuración > claude_desktop_config.json e incluye lo siguiente:

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "npx",
      "args": ["elevenlabs-mcp-enhanced"],
      "env": {
        "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

¡Eso es todo! No se necesita instalación: npx descargará y ejecutará el servidor automáticamente.

Opción 2: Usando Python (Método original)

Si prefieres la instalación original con Python:

Obtén tu clave de API en ElevenLabs.

Instala desde GitHub:

pip install git+https://github.com/199-biotechnologies/elevenlabs-mcp-enhanced.git

Configura Claude Desktop con:

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "python",
      "args": ["-m", "elevenlabs_mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

Si usas Windows, tendrás que habilitar el "Modo Desarrollador" en Claude Desktop para usar el servidor MCP. Haz clic en "Ayuda" en el menú de hamburguesa en la parte superior izquierda y selecciona "Habilitar Modo Desarrollador".

Otros clientes MCP

Usando npm/npx:

Para otros clientes como Cursor y Windsurf, puedes ejecutar el servidor directamente:

npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

Usando Python:

pip install elevenlabs-mcp
python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print para obtener la configuración. Pégala en el directorio de configuración apropiado especificado por tu cliente MCP.

Eso es todo. Tu cliente MCP ahora puede interactuar con ElevenLabs a través de estas herramientas:

Ejemplos de uso

⚠️ Advertencia: Se necesitan créditos de ElevenLabs para usar estas herramientas.

Prueba preguntarle a Claude:

"Crea un agente de IA que hable como un detective de cine negro y pueda responder preguntas sobre películas clásicas"
"Genera tres variaciones de voz para un personaje de dragón antiguo y sabio, luego elegiré mi voz favorita para añadirla a mi biblioteca de voces"
"Convierte esta grabación de mi voz para que suene como un caballero medieval"
"Crea un paisaje sonoro de una tormenta en una jungla densa con animales reaccionando al clima"
"Convierte este discurso en texto, identifica a los diferentes hablantes, y luego conviértelo de nuevo usando voces únicas para cada persona"

🆕 Modelo v3 - Guía de Inicio Rápido

🎯 ÁRBOL DE DECISIÓN:

¿Un solo hablante? → Usa text_to_speech con model="v3"
¿Múltiples hablantes? → Usa text_to_dialogue (automáticamente v3)
¿Necesitas ejemplos de etiquetas? → Llama a fetch_v3_tags() primero

📋 FLUJO DE TRABAJO RECOMENDADO PARA IA:

1. User: "Create an emotional story with sound effects"
2. AI: fetch_v3_tags() → Gets list of available tags
3. AI: search_voices("v3") → Gets v3-optimized voices
4. AI: text_to_dialogue(...) → Creates the story

Ejemplos de un Solo Hablante (text_to_speech):

"Genera: '[thoughtful] El universo es vasto... [piano] ...y está lleno de misterios.'"
"Crea una narración con: '[whispering] Mensaje secreto [footsteps] [door creaking]'"

Ejemplos Multi-Hablante (text_to_dialogue - SIEMPRE v3):

# Simple conversation
inputs = [
    {"text": "How are you?", "voice_name": "James"},
    {"text": "I'm great!", "voice_name": "Jane"}
]

# With emotion tags
inputs = [
    {"text": "[excited] I found treasure!", "voice_name": "James"},
    {"text": "[skeptical] Really? [pause] Where?", "voice_name": "Jane"}
]

⚠️ Requisitos de v3:

Estabilidad: DEBE ser 0.0, 0.5 o 1.0 (¡ningún otro valor!)
Mejores voces: James, Jane, Sarah, Mark, etc. (busca "v3" para encontrarlas)
Siempre consulta fetch_v3_tags() para ver las etiquetas de audio disponibles

🆕 Nuevas Funciones de Conversación

Con las herramientas de conversación mejoradas, ahora puedes:

"Obtén la transcripción de la conversación con ID abc123" (espera automáticamente a que se complete)
"Lista todas las conversaciones de mi agente y muéstrame las completadas"
"Obtén la conversación xyz789 inmediatamente sin esperar" (establece wait_for_completion=false)
"Muéstrame todas las conversaciones en formato JSON con marcas de tiempo"
"Obtén el historial de la conversación incluyendo datos de análisis"

Nota: La herramienta get_conversation ahora espera a que las conversaciones se completen por defecto (hasta 5 minutos), asegurando que siempre obtengas la transcripción completa.

Funciones opcionales

Puedes añadir la variable de entorno ELEVENLABS_MCP_BASE_PATH a claude_desktop_config.json para especificar la ruta base que el servidor MCP debe buscar y donde debe generar los archivos especificados con rutas relativas.

✅ Modelo v3: ¡Ahora Disponible Oficialmente!

El modelo v3 ahora está disponible oficialmente a través de la API de ElevenLabs. No se necesita proxy ni acceso especial: solo usa tu clave de API regular.

Novedades:

ID de modelo oficial eleven_v3
Endpoint de texto-a-diálogo en /v1/text-to-dialogue
Soporte de más de 70 idiomas
Límite de 3,000 caracteres por solicitud
Expresividad emocional mejorada

Uso: Simplemente establece model="v3" en text_to_speech() o usa text_to_dialogue() para contenido multi-hablante. El servidor ahora utiliza los endpoints oficiales de la API.

Contribuciones

Si quieres contribuir o ejecutar desde el código fuente:

Clona el repositorio:

git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcp

Crea un entorno virtual e instala las dependencias usando uv:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Copia .env.example a .env y añade tu clave de API de ElevenLabs:

cp .env.example .env
# Edit .env and add your API key

Ejecuta las pruebas para asegurarte de que todo funciona:

./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fast

Instala el servidor en Claude Desktop: mcp install elevenlabs_mcp/server.py
Depura y prueba localmente con MCP Inspector: mcp dev elevenlabs_mcp/server.py

Solución de Problemas

Los registros cuando se ejecuta con Claude Desktop se pueden encontrar en:

Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log

Tiempos de espera al usar ciertas herramientas

Ciertas operaciones de la API de ElevenLabs, como el diseño de voz y el aislamiento de audio, pueden tardar mucho tiempo en resolverse. Al usar el inspector de MCP en modo de desarrollo, podrías recibir errores de tiempo de espera a pesar de que la herramienta complete su tarea prevista.

Esto no debería ocurrir al usar un cliente como Claude.

MCP ElevenLabs: spawn uvx ENOENT

Si encuentras el error "MCP ElevenLabs: spawn uvx ENOENT", confirma su ruta absoluta ejecutando este comando en tu terminal:

which uvx

Una vez que obtengas la ruta absoluta (por ejemplo, /usr/local/bin/uvx), actualiza tu configuración para usar esa ruta (por ejemplo, "command": "/usr/local/bin/uvx"). Esto asegura que se haga referencia al ejecutable correcto.

Créditos

Fork Mejorado

Boris Djordjevic - Desarrollador Principal
Equipo 199 Longevity - Desarrollo y Pruebas

Servidor MCP Original de ElevenLabs

Jacek Duszenko - jacek@elevenlabs.io
Paul Asjes - paul.asjes@elevenlabs.io
Louis Jordan - louis@elevenlabs.io
Luke Harries - luke@elevenlabs.io

Este fork mejorado se basa en la excelente base creada por el equipo de ElevenLabs, añadiendo funciones críticas de IA conversacional para mejorar la interacción y el monitoreo de agentes.

Licencia

Este proyecto mantiene la misma licencia MIT que el servidor MCP original de ElevenLabs. Consulta LICENCIA para más detalles.