ElevenLabs

[!WARNING] Este servidor MCP local está obsoleto em favor do servidor MCP hospedado da ElevenLabs.

O servidor hospedado está disponível em https://api.elevenlabs.io/v1/mcp, sem necessidade de instalar ou executar nada localmente. Ele autentica com OAuth, então nenhuma chave de API é copiada para o seu cliente. Consulte a documentação do servidor MCP hospedado para conectar-se a partir do Claude, Cursor ou qualquer outro cliente MCP.

Este repositório não é mais mantido ativamente.

Servidor oficial da ElevenLabs Model Context Protocol (MCP) que permite interação com APIs poderosas 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 consulte o uv repositório para métodos de instalação adicionais.
3. Vá para Claude > Configurações > Desenvolvedor > Editar Config > 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 você estiver usando Windows, será necessário ativar o "Modo Desenvolvedor" no Claude Desktop para usar o servidor MCP. Clique em "Ajuda" no menu de hambúrguer no canto superior esquerdo e selecione "Ativar 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.

É 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 converta-a de volta usando vozes únicas para cada pessoa"

Recursos opcionais

Configuração de saída de arquivos

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

• ELEVENLABS_MCP_BASE_PATH: Especifique o caminho base para operações de arquivo (padrão: ~/Desktop). Este diretório também é o limite de segurança para arquivos de entrada: qualquer caminho passado para uma ferramenta que lê um arquivo local (por exemplo, speech_to_text, isolate_audio, speech_to_speech, video_to_music, upload_music_for_inpainting) deve ser resolvido dentro deste diretório, seja fornecido como caminho absoluto ou relativo. Caminhos fora dele — mesmo que absolutos e anteriormente aceitos — são rejeitados. Defina isso para um diretório que contenha tudo o que você precisa ler ou gravar.
• ELEVENLABS_MCP_OUTPUT_MODE: Controle 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 caminhos de arquivo

   "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
• Sem E/S de disco necessária — útil para ambientes conteinerizados ou sem servidor
• Os 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 arquivos, 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: A residência de dados é um recurso exclusivo para empresas. Consulte 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 da 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 usar com 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 receber erros de timeout apesar da ferramenta concluir 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.