Voice Call MCP Server

Permite que los asistentes de IA inicien y gestionen llamadas de voz usando Twilio y OpenAI.

GitHub
62
Prueba este MCPPatrocinado

Documentación

Voice Call MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a Claude y otros asistentes de IA iniciar y gestionar llamadas de voz utilizando Twilio y OpenAI (modelo GPT-4o Realtime).

Úsalo como base para comenzar tus exploraciones de llamadas de voz impulsadas por IA, ahorrar tiempo y desarrollar funcionalidades adicionales sobre él.

Demo

Diagrama de Secuencia

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

Características

  • Realiza llamadas telefónicas salientes a través de Twilio 📞
  • Procesa el audio de las llamadas en tiempo real con el modelo GPT-4o Realtime 🎙️
  • Cambio de idioma en tiempo real durante las llamadas 🌐
  • Indicaciones predefinidas para escenarios comunes de llamadas (como reservas de restaurantes) 🍽️
  • Tunelización automática de URL pública con ngrok 🔄
  • Manejo seguro de credenciales 🔒

¿Por qué MCP?

El Protocolo de Contexto de Modelo (MCP) cierra la brecha entre los asistentes de IA y las acciones del mundo real. Al implementar MCP, este servidor permite que modelos de IA como Claude puedan:

  1. Iniciar llamadas telefónicas reales en nombre de los usuarios
  2. Procesar y responder a conversaciones de audio en tiempo real
  3. Ejecutar tareas complejas que requieren comunicación por voz

Esta implementación de código abierto proporciona transparencia y personalización, permitiendo a los desarrolladores ampliar la funcionalidad mientras mantienen el control sobre sus datos y privacidad.

Requisitos

  • Node.js >= 22
    • Si necesitas actualizar Node.js, te recomendamos usar nvm (Node Version Manager): 
      nvm install 22
nvm use 22
  • Cuenta de Twilio con credenciales de API
  • Clave de API de OpenAI
  • Token de autenticación de Ngrok

Instalación

Instalación Manual

  1. Clona el repositorio

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

  2. Instala las dependencias y compila

    npm install
npm run build

Configuración

El servidor requiere varias variables de entorno:

  • TWILIO_ACCOUNT_SID: Tu SID de cuenta de Twilio
  • TWILIO_AUTH_TOKEN: Tu token de autenticación de Twilio
  • TWILIO_NUMBER: Tu número de Twilio
  • OPENAI_API_KEY: Tu clave de API de OpenAI
  • NGROK_AUTHTOKEN: Tu token de autenticación de ngrok
  • RECORD_CALLS: Establécelo en "true" para grabar llamadas (opcional)

Configuración de Claude Desktop

Para usar este servidor con Claude Desktop, agrega lo siguiente a tu archivo de configuración:

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"
      }
    }
  }
}

Después de eso, reinicia Claude Desktop para recargar la configuración. Si está conectado, deberías ver Voice Call en el menú 🔨.

Ejemplos de Interacciones con Claude

Aquí hay algunas formas naturales de interactuar con el servidor a través de Claude:

  1. Llamada simple:
Can you call +1-123-456-7890 and let them know I'll be 15 minutes late for our meeting?
  1. Reserva de 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. Programación de citas:
Please call Expert Dental NYC (+1-123-456-7899) and reschedule my Monday appointment to next Friday between 4–6pm.

Notas Importantes

  1. Formato de número de teléfono: Todos los números de teléfono deben estar en formato E.164 (por ejemplo, +11234567890)
  2. Límites de velocidad: Ten en cuenta los límites de velocidad y los precios de tu cuenta de Twilio y OpenAI
  3. Conversaciones de voz: La IA manejará conversaciones naturales en tiempo real
  4. Duración de la llamada: Ten en cuenta la duración de las llamadas, ya que afectan los costos de OpenAI API y Twilio
  5. Exposición pública: Ten en cuenta que el túnel de ngrok expone tu servidor públicamente para que Twilio pueda acceder a él (aunque con una URL aleatoria y protegido por un secreto aleatorio)

Solución de Problemas

Mensajes de error comunes y soluciones:

  1. "El número de teléfono debe estar en formato E.164"

    • Asegúrate de que el número de teléfono comience con "+" y el código de país

  2. "Credenciales inválidas"

    • Verifica tu TWILIO_ACCOUNT_SID y TWILIO_AUTH_TOKEN. Puedes copiarlos desde Twilio Console

  3. "Error de API de OpenAI"

    • Verifica que tu OPENAI_API_KEY sea correcta y tenga créditos suficientes

  4. "El túnel de Ngrok no pudo iniciarse"

    • Asegúrate de que tu NGROK_AUTHTOKEN sea válido y no esté vencido

  5. "OpenAI Realtime no detecta el final de la entrada de voz, o va con retraso."

    • A veces, puede haber problemas de codificación de voz entre Twilio y el operador de red del receptor. Prueba con un receptor diferente.

Contribuciones

¡Las contribuciones son bienvenidas! Aquí hay algunas áreas que buscamos mejorar:

  • Implementar soporte para múltiples modelos de IA más allá de la implementación actual
  • Agregar integración de base de datos para almacenar el historial de conversaciones localmente y hacerlo accesible para el contexto de IA
  • Mejorar la latencia y los tiempos de respuesta para mejorar las experiencias de llamada
  • Mejorar el manejo de errores y los mecanismos de recuperación
  • Agregar más plantillas de conversación predefinidas para escenarios comunes
  • Implementar un mejor monitoreo y análisis de llamadas

Si deseas contribuir, abre un issue para discutir tus ideas antes de enviar una solicitud de extracción.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para obtener más detalles.

Seguridad

No incluyas información sensible (como números de teléfono o credenciales de API) en issues de GitHub o solicitudes de extracción. Este servidor maneja comunicaciones sensibles; impleméntalo de manera responsable y asegúrate de que todas las credenciales se mantengan seguras.

¿Hora de una Nueva Misión?

Estamos contratando ingenieros para construir en la frontera de la IA de voz y integrarla en una telco de próxima generación.

¿Curioso? Dirígete a careers.popcorn.space 🍿 !