Voice Call MCP Server

Created By

MCP-Mirror8 months ago

Mirror of

Content

Voice Call MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to initiate and manage voice calls using Twilio and OpenAI (GPT-4o Realtime model).

Use this as a base to kick-start your AI-powered voice calling explorations, save time and develop additional functionality on top of it.

Demo

Sequence Diagram

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

Features

Make outbound phone calls via Twilio 📞
Process call audio in real-time with GPT-4o Realtime model 🎙️
Real-time language switching during calls 🌐
Pre-built prompts for common calling scenarios (like restaurant reservations) 🍽️
Automatic public URL tunneling with ngrok 🔄
Secure handling of credentials 🔒

Why MCP?

The Model Context Protocol (MCP) bridges the gap between AI assistants and real-world actions. By implementing MCP, this server allows AI models like Claude to:

Initiate actual phone calls on behalf of users
Process and respond to real-time audio conversations
Execute complex tasks requiring voice communication

This open-source implementation provides transparency and customizability, allowing developers to extend functionality while maintaining control over their data and privacy.

Requirements

Node.js >= 22
- If you need to update Node.js, we recommend using nvm (Node Version Manager):
```
nvm install 22
nvm use 22
```
Twilio account with API credentials
OpenAI API key
Ngrok Authtoken

Installation

Manual Installation

Clone the repository

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

Install dependencies and build
```
npm install
npm run build
```

Configuration

The server requires several environment variables:

TWILIO_ACCOUNT_SID: Your Twilio account SID
TWILIO_AUTH_TOKEN: Your Twilio auth token
TWILIO_NUMBER: Your Twilio number
OPENAI_API_KEY: Your OpenAI API key
NGROK_AUTHTOKEN: Your ngrok authtoken
RECORD_CALLS: Set to "true" to record calls (optional)

Claude Desktop Configuration

To use this server with Claude Desktop, add the following to your configuration file:

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

After that, restart Claude Desktop to reload the configuration. If connected, you should see Voice Call under the 🔨 menu.

Example Interactions with Claude

Here are some natural ways to interact with the server through Claude:

Simple call:

Can you call +1-123-456-7890 and let them know I'll be 15 minutes late for our meeting?

Restaurant reservation:

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.

Appointment scheduling:

Please call Expert Dental NYC (+1-123-456-7899) and reschedule my Monday appointment to next Friday between 4–6pm.

Important Notes

Phone Number Format: All phone numbers must be in E.164 format (e.g., +11234567890)
Rate Limits: Be aware of your Twilio and OpenAI account's rate limits and pricing
Voice Conversations: The AI will handle natural conversations in real-time
Call Duration: Be mindful of call durations as they affect OpenAI API and Twilio costs
Public Exposure: Be aware that the ngrok tunnel exposes your server publicly for Twilio to reach it (though with a random URL and protected by a random secret)

Troubleshooting

Common error messages and solutions:

"Phone number must be in E.164 format"
- Make sure the phone number starts with "+" and the country code
"Invalid credentials"
- Double-check your TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN. You can copy them from the Twilio Console
"OpenAI API error"
- Verify your OPENAI_API_KEY is correct and has sufficient credits
"Ngrok tunnel failed to start"
- Ensure your NGROK_AUTHTOKEN is valid and not expired
"OpenAI Realtime does not detect the end of voice input, or is lagging."
- Sometimes, there might be voice encoding issues between Twilio and the receiver's network operator. Try using a different receiver.

Contributing

Contributions are welcome! Here are some areas we're looking to improve:

Implement support for multiple AI models beyond the current implementation
Add database integration to store conversation history locally and make it accessible for AI context
Improve latency and response times to enhance call experiences
Enhance error handling and recovery mechanisms
Add more pre-built conversation templates for common scenarios
Implement improved call monitoring and analytics

If you'd like to contribute, please open an issue to discuss your ideas before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Security

Please do not include any sensitive information (like phone numbers or API credentials) in GitHub issues or pull requests. This server handles sensitive communications; deploy it responsibly and ensure all credentials are kept secure.