Voice Call MCP Server

Permite que assistentes de IA iniciem e gerenciem chamadas de voz usando Twilio e OpenAI.

GitHub
62
Experimente este MCPPatrocinado

Documentação

Voice Call MCP Server

Um servidor Model Context Protocol (MCP) que permite que Claude e outros assistentes de IA iniciem e gerenciem chamadas de voz usando Twilio e OpenAI (modelo GPT-4o Realtime).

Use isso como base para iniciar suas explorações de chamadas de voz com IA, economize tempo e desenvolva funcionalidades adicionais em cima dela.

Demo

Diagrama de Sequência

sequenceDiagram
    participant AI as AI Assistant (e.g., Claude)
    participant MCP as MCP Server
    participant Twilio as Twilio
    participant Phone as Destination Phone
    participant OpenAI as OpenAI
    
    AI->>MCP: 1) Initiate outbound call request <br>(POST /calls)
    MCP->>Twilio: 2) Place outbound call via Twilio API
    Twilio->>Phone: 3) Ring the destination phone
    Twilio->>MCP: 4) Call status updates & audio callbacks (webhooks)
    MCP->>OpenAI: 5) Forward real-time audio to OpenaAI's realtime model
    OpenAI->>MCP: 6) Return voice stream
    MCP->>Twilio: 7) Send voice stream
    Twilio->>Phone: 8) Forward voice stream
    Note over Phone: Two-way conversation continues <br>until the call ends

Recursos

  • Faça chamadas telefônicas de saída via Twilio 📞
  • Processe áudio de chamadas em tempo real com o modelo GPT-4o Realtime 🎙️
  • Troca de idioma em tempo real durante chamadas 🌐
  • Prompts pré-construídos para cenários comuns de chamadas (como reservas em restaurantes) 🍽️
  • Tunelamento automático de URL pública com ngrok 🔄
  • Tratamento seguro de credenciais 🔒

Por que MCP?

O Model Context Protocol (MCP) preenche a lacuna entre assistentes de IA e ações do mundo real. Ao implementar MCP, este servidor permite que modelos de IA como Claude:

  1. Iniciar chamadas telefônicas reais em nome dos usuários
  2. Processar e responder a conversas de áudio em tempo real
  3. Executar tarefas complexas que exigem comunicação por voz

Esta implementação de código aberto oferece transparência e personalização, permitindo que desenvolvedores estendam a funcionalidade enquanto mantêm controle sobre seus dados e privacidade.

Requisitos

  • Node.js >= 22
    • Se você precisar atualizar o Node.js, recomendamos usar nvm (Node Version Manager): 
      nvm install 22
nvm use 22
  • Conta Twilio com credenciais de API
  • Chave de API da OpenAI
  • Authtoken do Ngrok

Instalação

Instalação Manual

  1. Clone o repositório

    git clone https://github.com/lukaskai/voice-call-mcp-server.git
cd voice-call-mcp-server

  2. Instale as dependências e faça o build

    npm install
npm run build

Configuração

O servidor requer várias variáveis de ambiente:

  • TWILIO_ACCOUNT_SID: Seu SID da conta Twilio
  • TWILIO_AUTH_TOKEN: Seu token de autenticação Twilio
  • TWILIO_NUMBER: Seu número Twilio
  • OPENAI_API_KEY: Sua chave de API da OpenAI
  • NGROK_AUTHTOKEN: Seu authtoken do ngrok
  • RECORD_CALLS: Defina como "true" para gravar chamadas (opcional)

Configuração do Claude Desktop

Para usar este servidor com o Claude Desktop, adicione o seguinte ao seu arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "voice-call": {
      "command": "node",
      "args": ["/path/to/your/mcp-new/dist/start-all.cjs"],
      "env": {
        "TWILIO_ACCOUNT_SID": "your_account_sid",
        "TWILIO_AUTH_TOKEN": "your_auth_token",
        "TWILIO_NUMBER": "your_e.164_format_number",
        "OPENAI_API_KEY": "your_openai_api_key",
        "NGROK_AUTHTOKEN": "your_ngrok_authtoken"
      }
    }
  }
}

Depois disso, reinicie o Claude Desktop para recarregar a configuração. Se conectado, você deve ver Voice Call no menu 🔨.

Exemplos de Interações com Claude

Aqui estão algumas maneiras naturais de interagir com o servidor através do Claude:

  1. Chamada simples:
Can you call +1-123-456-7890 and let them know I'll be 15 minutes late for our meeting?
  1. Reserva em restaurante:
Please call Delicious Restaurant at +1-123-456-7890 and make a reservation for 4 people tonight at 7:30 PM. Please speak in German.
  1. Agendamento de consulta:
Please call Expert Dental NYC (+1-123-456-7899) and reschedule my Monday appointment to next Friday between 4–6pm.

Notas Importantes

  1. Formato do Número de Telefone: Todos os números de telefone devem estar no formato E.164 (ex.: +11234567890)
  2. Limites de Taxa: Esteja ciente dos limites de taxa e preços da sua conta Twilio e OpenAI
  3. Conversas por Voz: A IA lidará com conversas naturais em tempo real
  4. Duração da Chamada: Esteja atento à duração das chamadas, pois elas afetam os custos da API OpenAI e Twilio
  5. Exposição Pública: Esteja ciente de que o túnel ngrok expõe seu servidor publicamente para que o Twilio o alcance (embora com uma URL aleatória e protegido por um segredo aleatório)

Solução de Problemas

Mensagens de erro comuns e soluções:

  1. "O número de telefone deve estar no formato E.164"

    • Certifique-se de que o número de telefone comece com "+" e o código do país

  2. "Credenciais inválidas"

    • Verifique novamente seu TWILIO_ACCOUNT_SID e TWILIO_AUTH_TOKEN. Você pode copiá-los do Console Twilio

  3. "Erro na API da OpenAI"

    • Verifique se sua OPENAI_API_KEY está correta e tem créditos suficientes

  4. "Falha ao iniciar o túnel ngrok"

    • Certifique-se de que seu NGROK_AUTHTOKEN seja válido e não esteja expirado

  5. "O OpenAI Realtime não detecta o fim da entrada de voz ou está com atraso."

    • Às vezes, pode haver problemas de codificação de voz entre a Twilio e a operadora de rede do receptor. Tente usar um receptor diferente.

Contribuindo

Contribuições são bem-vindas! Aqui estão algumas áreas que queremos melhorar:

  • Implementar suporte para múltiplos modelos de IA além da implementação atual
  • Adicionar integração com banco de dados para armazenar o histórico de conversas localmente e torná-lo acessível para contexto de IA
  • Melhorar a latência e os tempos de resposta para aprimorar as experiências de chamada
  • Aprimorar o tratamento de erros e mecanismos de recuperação
  • Adicionar mais modelos de conversa pré-construídos para cenários comuns
  • Implementar monitoramento e análises de chamadas aprimorados

Se você quiser contribuir, abra uma issue para discutir suas ideias antes de enviar um pull request.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Segurança

Por favor, não inclua informações sensíveis (como números de telefone ou credenciais de API) em issues do GitHub ou pull requests. Este servidor lida com comunicações sensíveis; implante-o com responsabilidade e garanta que todas as credenciais sejam mantidas em segurança.

Hora de uma Nova Missão?

Estamos contratando engenheiros para construir na fronteira da IA de voz — e integrá-la a uma operadora de telecomunicações de próxima geração.

Curioso? Acesse careers.popcorn.space 🍿 !