Callcenter.js MCP

🚀 CallCenter.js MCP + CLI

An MCP Server, CLI tool, and API that enables phone calls via VoIP on your behalf.

Just inform Claude of your desired task, and it will initiate the call and manage the conversation for you. This is essentially an MCP Server that bridges between OpenAI's Real-Time Voice API and your VoIP connection, allowing it to make calls on your behalf.

🚀 Quick Start

Option 1: Run Instantly with npx (No Installation) ⚡

The fastest way to try it out:

# Set environment variables (or create .env file)
export SIP_USERNAME="your_extension"
export SIP_PASSWORD="your_password"
export SIP_SERVER_IP="192.168.1.1"
export OPENAI_API_KEY="sk-your-key-here"

# Run directly from GitHub (no installation needed!)
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

Or using a .env file:

# Create .env file
cat > .env << EOF
SIP_USERNAME=your_extension
SIP_PASSWORD=your_password
SIP_SERVER_IP=192.168.1.1
OPENAI_API_KEY=sk-your-key-here
SIP_PROVIDER=fritz-box
OPENAI_VOICE=alloy
EOF

# Run from GitHub (loads .env automatically)  
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"

Note: The first run may display build warnings if you don't have C++ build tools, but it will work fine with the G.711 codec fallback (standard phone quality). For significantly better audio quality, install build tools first to enable the G.722 wideband codec.

Option 2: Local Installation

Prerequisites

• Node.js 20+
• Python 3.x + Build tools (for G.722 wideband audio - much better call quality)
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Visual Studio Build Tools
  • Linux: build-essential package
• OpenAI API key

Note: Without build tools, the system automatically falls back to G.711 (standard phone quality). G.722 provides twice the bandwidth for clearer, more natural conversations.

Installation

# Clone and install
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# Copy example configuration
cp config.example.json config.json

Configuration

Edit config.json with your settings:

{
  "sip": {
    "username": "your_sip_username",
    "password": "your_sip_password", 
    "serverIp": "192.168.1.1",
    "serverPort": 5060,
    "provider": "fritz-box"
  },
  "ai": {
    "openaiApiKey": "sk-your-openai-api-key-here",
    "voice": "alloy",
    "instructions": "You are a helpful AI assistant making phone calls on behalf of users.",
    "userName": "Your Name"
  }
}

✨ Features

• 🎙️ Multiple Codec Support: G.722 wideband (16kHz) + G.711 fallback for broad compatibility
• 🤖 AI-Powered Conversations: Utilizes OpenAI's Real-Time Voice API for actual calls, with the o3-mini model (OpenAI's reasoning model) for instruction generation
• 🌐 Expanded SIP Support: Configurations for common SIP providers (Fritz!Box tested, others experimental)
• 🔧 Smart Configuration: Automatically detects provider requirements and optimizes settings
• 📞 Enterprise-Ready: Supports advanced SIP features (STUN/TURN, session timers, transport fallback)
• 🔄 Robust Connection Management: Automatic reconnection with intelligent error handling
• ✅ Built-in Validation: Comprehensive configuration validation with network testing
• 🎯 Provider Profiles: Pre-configured settings for popular SIP systems
• 🔌 MCP Server: Integrates with Claude Code and other MCP clients
• 📚 TypeScript API: Programmatic library for building voice applications
• 📝 Call Brief Processing: Natural language call instructions using the o3-mini model
• 🎵 Optional Call Recording: Stereo WAV recording with caller/AI separation

📦 Installation

Option 1: Run Instantly with npx (No Installation) ⚡

# Set environment variables (or create .env file)
export SIP_USERNAME="your_extension"
export SIP_PASSWORD="your_password"
export SIP_SERVER_IP="192.168.1.1"
export OPENAI_API_KEY="sk-your-key-here"

# Run directly from GitHub (no installation needed!)
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

Option 2: Local Installation

# Clone and install
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# Copy example configuration
cp config.example.json config.json

💻 Usage Examples

Basic Usage

# ✅ RECOMMENDED: Use brief for natural language goals
npm start call "+1234567890" --brief "Call the restaurant and book a table for 2 at 7pm tonight" --user-name "John Doe"

# ✅ RECOMMENDED: Brief works for any call type
npm start call "+1234567890" --brief "Call to check appointment availability for John Doe"

# ⚠️ ONLY use instructions for very specific, custom behavior
npm start call "+1234567890" --instructions "You must follow this exact script: Say hello, ask for manager, then hang up"

# Other examples with brief
npm start call "+1234567890" --record "meeting.wav" --duration 300 --brief "Conference call to discuss project status"
npm start call "+1234567890" --log-level verbose --brief "Test call to verify connectivity"

Advanced Usage

import { makeCall, createAgent } from 'callcenter.js';

// Simple call with brief
const result = await makeCall({
  number: '+1234567890',
  brief: 'Call Bocca di Bacco and book a table for 2 at 19:30 for Torben',
  userName: 'Torben',
  config: 'config.json'
});

console.log(`Call duration: ${result.duration}s`);
console.log(`Transcript: ${result.transcript}`);

// Advanced usage with agent instance
const agent = await createAgent('config.json');

agent.on('callEnded', () => {
  console.log('Call finished!');
});

await agent.makeCall({ 
  targetNumber: '+1234567890',
  duration: 300 
});

📚 Documentation

API Reference

makeCall(options: CallOptions): Promise<CallResult>

Make a phone call with the AI agent.

CallOptions

interface CallOptions {
  number: string;                    // Phone number to call
  duration?: number;                 // Call duration in seconds
  config?: string | Config;          // Configuration file path or object
  instructions?: string;             // Direct AI instructions (highest priority)
  brief?: string;                    // Call brief to generate instructions from
  userName?: string;                 // Your name for the AI to use
  recording?: boolean | string;      // Enable recording with optional filename
  logLevel?: 'quiet' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
  colors?: boolean;                  // Enable colored output
  timestamps?: boolean;              // Enable timestamps in logs
}

CallResult

interface CallResult {
  callId?: string;                   // Call ID if successful
  duration: number;                  // Call duration in seconds
  transcript?: string;               // Full conversation transcript
  success: boolean;                  // Whether call was successful
  error?: string;                    // Error message if failed
}

createAgent(config, options?): Promise<VoiceAgent>

Create a VoiceAgent instance for advanced use cases.

const agent = await createAgent('config.json', {
  enableCallRecording: true,
  recordingFilename: 'call.wav'
});

// Event handlers
agent.on('callInitiated', ({ callId, target }) => {
  console.log(`Call ${callId} started to ${target}`);
});

agent.on('callEnded', () => {
  console.log('Call ended');
});

agent.on('error', (error) => {
  console.error('Call error:', error.message);
});

Configuration Structure

interface Config {
  sip: {
    username: string;
    password: string;
    serverIp: string;
    serverPort?: number;
    provider?: string;
    stunServers?: string[];
    turnServers?: TurnServer[];
  };
  ai: {
    openaiApiKey: string;
    voice?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
    instructions?: string;
    brief?: string;
    userName?: string;
  };
  logging?: {
    level?: string;
  };
}

Environment Variables

All configuration options can be set via environment variables (useful for npx usage):

Required Variables:

SIP_USERNAME=your_extension
SIP_PASSWORD=your_password  
SIP_SERVER_IP=192.168.1.1
OPENAI_API_KEY=sk-your-key-here
USER_NAME="Your Name"                                     # Required when using --brief

Optional Variables:

# SIP Configuration
SIP_SERVER_PORT=5060
SIP_LOCAL_PORT=5060
SIP_PROVIDER=fritz-box                                    # fritz-box, asterisk, cisco, 3cx, generic
STUN_SERVERS="stun:stun.l.google.com:19302,stun:stun2.l.google.com:19302"
SIP_TRANSPORTS="udp,tcp"

# OpenAI Configuration  
OPENAI_VOICE=alloy                                        # alloy, echo, fable, onyx, nova, shimmer
OPENAI_INSTRUCTIONS="Your custom AI instructions"

# Advanced SIP Features
SESSION_TIMERS_ENABLED=true
SESSION_EXPIRES=1800
SESSION_MIN_SE=90
SESSION_REFRESHER=uac

Priority order: CLI flags > Config file > Environment variables

🔧 Technical Details

Smart Connection Management

• Automatic Reconnection: Exponential backoff with provider-specific error handling
• Transport Fallback: UDP → TCP → TLS based on what works
• Provider-Aware Error Recovery: Different strategies for Fritz Box vs. Asterisk vs. Cisco
• Network Change Handling: Adapts to network connectivity changes

Enhanced SIP Protocol Support

• STUN/TURN Integration: NAT traversal for cloud and enterprise deployments
• Session Timers (RFC 4028): Connection stability for long calls
• PRACK Support (RFC 3262): Reliable provisional responses for enterprise systems
• Multiple Transports: UDP, TCP, TLS with intelligent fallback

Configuration Intelligence

• Provider Auto-Detection: Identifies provider from SIP domain/IP
• Requirements Validation: Ensures all provider-specific needs are met
• Network Testing: Real connectivity tests to SIP servers and STUN servers
• Optimization Suggestions: Actionable recommendations for better performance

📄 License

MIT License - see LICENSE for details.

Third-Party Components

• G.722 Codec: Public domain and BSD licensed implementations
• SIP Protocol: Based on sipjs-udp (MIT licensed)
• Dependencies: Various open source licenses (see package.json)

⚠️ Important Note

This project is a side project coded in a weekend. There are no guard rails. Your MCP client can call any number with this, even if you don't ask it to. It has been tested, and during testing, it called a random number at night "for testing" and played back scary low-pitched noises, then claimed it called the user's number. So use it at your own risk.

💡 Usage Tip

Use --brief instead of --instructions for better results. The --brief option uses OpenAI's o3-mini model to generate sophisticated instructions from your simple description, while --instructions sends your text directly to the Real-Time Voice API. Since the Real-Time Voice API is optimized for speed (not sophistication), --brief typically produces much better call outcomes.