ElevenLabs MCP Enhanced

Geração de texto para fala com recursos de histórico de conversas usando a API ElevenLabs.

Documentação

ElevenLabs MCP Enhanced

Fork aprimorado do servidor oficial ElevenLabs MCP com recursos adicionais de IA conversacional, incluindo histórico de conversas e recuperação de transcrições.

Esta versão aprimorada é desenvolvida e mantida por Boris Djordjevic e pela equipe 199 Longevity.

🚀 Novidades neste Fork

Esta versão aprimorada adiciona recursos críticos de IA conversacional ausentes no original:

🤖 Melhorias Amigáveis para IA (v1.0.0)

✅ API v3 Oficial: Agora usa endpoints oficiais da ElevenLabs - sem necessidade de proxy!
🎯 Padrões Inteligentes de Voz: search_voices() agora retorna vozes comuns que funcionam instantaneamente
📚 Mensagens de Erro Educativas: Erros guiam agentes de IA ao sucesso com exemplos
💡 Orientação Clara de Ferramentas: Sem mais confusão entre ferramentas de um ou vários falantes
🎤 IDs de Voz v3 Precisos: Todas as 20 vozes otimizadas para v3 agora têm IDs e descrições corretas
🏯 Divisão Automática de Diálogos Longos: Divide automaticamente diálogos com mais de 3000 caracteres em vários arquivos
🎯 Ajuste Automático de Estabilidade: Valores de estabilidade inválidos são arredondados automaticamente para a opção válida mais próxima (0.0, 0.5, 1.0)
🏷️ Simplificação Inteligente de Tags: Tags complexas são convertidas automaticamente para tags v3 válidas para melhor qualidade
⏱️ Timeouts Dinâmicos: Evita timeouts em diálogos complexos calculando tempos de espera adequados

🆕 Suporte ao Modelo v3 da ElevenLabs (Oficial)

🎭 Expressividade Aprimorada: Use o modelo v3 oficial com o parâmetro model="v3"
🎤 Tags de Áudio: Adicione emoções e efeitos sonoros como [thoughtful], [crying], [laughing], [piano]
👥 Diálogo com Vários Falantes: Gere conversas naturais entre vários falantes
✨ Aprimoramento de Diálogo: Aprimore automaticamente seu diálogo com formatação e tags adequadas
🌍 Mais de 70 Idiomas: v3 suporta síntese multilíngue com controle emocional
✅ API Oficial: Agora usa o endpoint oficial de texto para diálogo da ElevenLabs

🎙️ Recursos de IA Conversacional

Histórico de Conversas: Recupere detalhes completos da conversa, incluindo transcrições
📝 Acesso a Transcrições: Obtenha transcrições de conversas em vários formatos (texto simples, timestamps, JSON)
⏳ Monitoramento em Tempo Real: Aguarde a conclusão de conversas em andamento e recupere os resultados
🔍 Pesquisa de Conversas: Liste e filtre conversas por agente, status e mais
🎨 Formatação Aprimorada: Formatação consistente em todas as operações de listagem

Sobre

Este é um fork aprimorado do servidor oficial ElevenLabs Model Context Protocol (MCP) que permite interação com poderosas APIs de Texto para Fala e processamento de áudio. Este servidor permite que clientes MCP como Claude Desktop, Cursor, Windsurf, OpenAI Agents e outros gerem fala, clonem vozes, transcrevam áudio, gerenciem agentes de IA conversacional e agora recuperem histórico de conversas.

🚀 Instalação Rápida

Instalação Zero (Recomendado)

Nenhuma instalação necessária! Basta usar npx:

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

Instalação Global

Instale uma vez, use em qualquer lugar:

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

Variável de Ambiente

Defina sua chave de API uma vez:

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

📋 Requisitos

Node.js 16+ (para npm/npx)
Python 3.11+ (gerenciado automaticamente pelo pacote npm)
Chave de API da ElevenLabs - Obtenha uma em elevenlabs.io

Início Rápido com Claude Desktop

Opção 1: Usando npm/npx (Recomendado - Nenhuma instalação necessária!)

Obtenha sua chave de API em ElevenLabs. Existe um plano gratuito com 10 mil créditos por mês.
Vá para Claude > Configurações > Desenvolvedor > Editar Config > claude_desktop_config.json para incluir o seguinte:

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

É isso! Nenhuma instalação necessária - o npx baixará e executará o servidor automaticamente.

Opção 2: Usando Python (Método original)

Obtenha sua chave de API em ElevenLabs.

Instale a partir do GitHub:

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

Configure o Claude Desktop com:

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

Se você estiver usando Windows, precisará ativar o "Modo Desenvolvedor" no Claude Desktop para usar o servidor MCP. Clique em "Ajuda" no menu hambúrguer no canto superior esquerdo e selecione "Ativar Modo Desenvolvedor".

Outros clientes MCP

Usando npm/npx:

Para outros clientes como Cursor e Windsurf, você pode executar o servidor diretamente:

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 obter a configuração. Cole-a no diretório de configuração apropriado especificado pelo seu cliente MCP.

É isso. Seu cliente MCP agora pode interagir com a ElevenLabs por meio destas ferramentas:

Exemplo de uso

⚠️ Aviso: Créditos da ElevenLabs são necessários para usar estas ferramentas.

Tente perguntar ao Claude:

"Crie um agente de IA que fale como um detetive de filmes noir e possa responder perguntas sobre filmes clássicos"
"Gere três variações de voz para um personagem de dragão antigo e sábio, então escolherei minha voz favorita para adicionar à minha biblioteca de vozes"
"Converta esta gravação da minha voz para soar como um cavaleiro medieval"
"Crie uma paisagem sonora de uma tempestade em uma selva densa com animais reagindo ao clima"
"Transforme esta fala em texto, identifique diferentes falantes e depois converta-a de volta usando vozes únicas para cada pessoa"

🆕 Modelo v3 - Guia de Início Rápido

🎯 ÁRVORE DE DECISÃO:

Um único falante? → Use text_to_speech com model="v3"
Vários falantes? → Use text_to_dialogue (automaticamente v3)
Precisa de exemplos de tags? → Chame fetch_v3_tags() primeiro

📋 FLUXO DE TRABALHO 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

Exemplos de um único falante (text_to_speech):

"Gere: '[thoughtful] O universo é vasto... [piano] ...e cheio de mistérios.'"
"Crie narração com: '[whispering] Mensagem secreta [footsteps] [door creaking]'"

Exemplos de vários falantes (text_to_dialogue - SEMPRE 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 do v3:

Estabilidade: DEVE ser 0.0, 0.5 ou 1.0 (nenhum outro valor!)
Melhores vozes: James, Jane, Sarah, Mark, etc. (pesquise "v3" para encontrá-las)
Sempre verifique fetch_v3_tags() para tags de áudio disponíveis

🆕 Novos Recursos de Conversa

Com as ferramentas de conversa aprimoradas, você agora pode:

"Obtenha a transcrição da conversa do ID abc123" (aguarda automaticamente a conclusão)
"Liste todas as conversas do meu agente e mostre-me as concluídas"
"Obtenha a conversa xyz789 imediatamente sem esperar" (defina wait_for_completion=false)
"Mostre-me todas as conversas em formato JSON com timestamps"
"Obtenha o histórico da conversa incluindo dados de análise"

Nota: A ferramenta get_conversation agora aguarda a conclusão das conversas por padrão (até 5 minutos), garantindo que você sempre obtenha a transcrição completa.

Recursos opcionais

Você pode adicionar a variável de ambiente ELEVENLABS_MCP_BASE_PATH ao claude_desktop_config.json para especificar o caminho base que o servidor MCP deve procurar e gerar arquivos especificados com caminhos relativos.

✅ Modelo v3 - Agora Oficialmente Disponível!

O modelo v3 agora está oficialmente disponível através da API da ElevenLabs! Nenhum proxy ou acesso especial é necessário - basta usar sua chave de API normal.

O que há de novo:

ID do modelo oficial eleven_v3
Endpoint de texto para diálogo em /v1/text-to-dialogue
Suporte a mais de 70 idiomas
Limite de 3.000 caracteres por solicitação
Expressividade emocional aprimorada

Uso: Basta definir model="v3" em text_to_speech() ou usar text_to_dialogue() para conteúdo com vários falantes. O servidor agora usa os endpoints oficiais da API.

Contribuindo

Se você quiser contribuir ou executar a partir do código-fonte:

Clone o repositório:

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

Crie um ambiente virtual e instale as dependências usando uv:

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

Copie .env.example para .env e adicione sua chave de API da ElevenLabs:

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

Execute os testes para garantir que tudo está funcionando:

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

Instale o servidor no Claude Desktop: mcp install elevenlabs_mcp/server.py
Depure e teste localmente com o MCP Inspector: mcp dev elevenlabs_mcp/server.py

Solução de problemas

Os logs ao executar com o Claude Desktop podem ser encontrados em:

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

Timeouts ao usar certas ferramentas

Certas operações da API da ElevenLabs, como design de voz e isolamento de áudio, podem levar muito tempo para serem resolvidas. Ao usar o inspetor MCP no modo de desenvolvimento, você pode obter erros de timeout mesmo que a ferramenta conclua sua tarefa pretendida.

Isso não deve ocorrer ao usar um cliente como o Claude.

MCP ElevenLabs: spawn uvx ENOENT

Se você encontrar o erro "MCP ElevenLabs: spawn uvx ENOENT", confirme seu caminho absoluto executando este comando no seu terminal:

which uvx

Depois de obter o caminho absoluto (por exemplo, /usr/local/bin/uvx), atualize sua configuração para usar esse caminho (por exemplo, "command": "/usr/local/bin/uvx"). Isso garante que o executável correto seja referenciado.

Créditos

Fork Aprimorado

Boris Djordjevic - Desenvolvedor Principal
Equipe 199 Longevity - Desenvolvimento e Testes

Servidor MCP Original da ElevenLabs

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

Este fork aprimorado se baseia na excelente fundação criada pela equipe da ElevenLabs, adicionando recursos críticos de IA conversacional para melhor interação e monitoramento de agentes.

Licença

Este projeto mantém a mesma licença MIT do servidor MCP original da ElevenLabs. Consulte LICENSE para obter detalhes.