ElevenLabs

Servidor oficial ElevenLabs Model Context Protocol (MCP) que permite a 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 e muito mais.

Início rápido com Claude Desktop

1. Obtenha sua chave de API em ElevenLabs. Há um plano gratuito com 10 mil créditos por mês.
2. Instale o uv (gerenciador de pacotes Python), instale com curl -LsSf https://astral.sh/uv/install.sh | sh ou veja o repositório do uv para métodos de instalação adicionais.
3. Vá para Claude > Configurações > Desenvolvedor > Editar Configuração > claude_desktop_config.json para incluir o seguinte:

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

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

Outros clientes MCP

Para outros clientes como Cursor e Windsurf, execute:

1. pip install elevenlabs-mcp
2. 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.

Pronto. Seu cliente MCP agora pode interagir com o ElevenLabs através destas ferramentas:

Exemplo de uso

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

Experimente 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 sábio e ancião, depois 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 locutores e depois converta de volta usando vozes únicas para cada pessoa"

Recursos opcionais

Configuração de saída de arquivo

Você pode configurar como o servidor MCP lida com as saídas de arquivo usando estas variáveis de ambiente no seu claude_desktop_config.json:

• ELEVENLABS_MCP_BASE_PATH: Especifica o caminho base para operações de arquivo com caminhos relativos (padrão: ~/Desktop)
• ELEVENLABS_MCP_OUTPUT_MODE: Controla como os arquivos gerados são retornados (padrão: files)

Modos de saída

A variável de ambiente ELEVENLABS_MCP_OUTPUT_MODE suporta três modos:

1. files (padrão): Salva arquivos no disco e retorna os caminhos dos arquivos

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "files"
   }
   

2. resources: Retorna arquivos como recursos MCP; dados binários são codificados em base64, texto é retornado como texto UTF-8

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
   }
   

3. both: Salva arquivos no disco E retorna como recursos MCP

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "both"
   }
   

Benefícios do Modo Recurso:

• Os arquivos são retornados diretamente na resposta MCP como dados codificados em base64
• Nenhuma E/S de disco necessária - útil para ambientes conteinerizados ou sem servidor
• Clientes MCP podem acessar o conteúdo do arquivo imediatamente sem acesso ao sistema de arquivos
• No modo both, os recursos podem ser buscados posteriormente usando o padrão de URI elevenlabs://filename

Casos de uso:

• files: Fluxos de trabalho tradicionais baseados em arquivo, desenvolvimento local
• resources: Ambientes em nuvem, clientes MCP sem acesso ao sistema de arquivos
• both: Máxima flexibilidade, cache e cenários de compartilhamento de recursos

Chaves de residência de dados

Você pode especificar a região de residência de dados com a variável de ambiente ELEVENLABS_API_RESIDENCY. O padrão é "us".

Nota: Residência de dados é um recurso exclusivo para planos empresariais. Veja a documentação para mais detalhes.

Contribuindo

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

1. Clone o repositório:

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

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

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

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

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

4. Execute os testes para garantir que tudo está funcionando:

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

5. Instale o servidor no Claude Desktop: mcp install elevenlabs_mcp/server.py

6. 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 do ElevenLabs, como design de voz e isolamento de áudio, podem levar muito tempo para serem concluídas. Ao usar o MCP Inspector no modo de desenvolvimento, você pode receber 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 (ex.: /usr/local/bin/uvx), atualize sua configuração para usar esse caminho (ex.: "command": "/usr/local/bin/uvx"). Isso garante que o executável correto seja referenciado.