Callcenter.js

CallCenter.js MCP + CLI

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

Just tell Claude what you want to accomplish, and it will call and handle the conversation for you. This is essentially an MCP Server that bridges between OpenAI's Real-Time Voice API and your VoIP connection to call people on your behalf.

⚠️ Vibe-coded side project! Please do not use this in any kind of professional context. This 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. In fact, it has done so during testing - it called a random number during the night "for testing" and played back scary low-pitched noises - then claimed it called MY number. So YMMV, no warranties. See disclaimer below.

📞 Example: Order Pizza with Claude

You: "Can you call Tony's Pizza and order a large pepperoni pizza for delivery to 123 Main St? My name is John and my number is 555-0123."

Claude automatically calls the restaurant:

⏺ mcp__callcenter_js__simple_call(phone_number: "+15551234567", 
                                    brief: "Call Tony's Pizza and order a large pepperoni pizza for delivery to 123 Main St. Customer name is John, phone number 555-0123", 
                                    caller_name: "John")
  ⎿ # Simple Call Result
    
    **Status:** ✅ Success  
    **Duration:** 3 minutes 24 seconds
    **Call ID:** abc123xyz
    
    ## Call Transcript
    
    [14:23:15] 🎤 HUMAN: Tony's Pizza, how can I help you?
    [14:23:15] 🤖 ASSISTANT: Hi! I'm calling on behalf of John to place a delivery order.
    [14:23:20] 🎤 HUMAN: Sure! What would you like?
    [14:23:20] 🤖 ASSISTANT: I'd like to order one large pepperoni pizza for delivery please.
    [14:23:25] 🎤 HUMAN: Large pepperoni, got it. What's the delivery address?
    [14:23:25] 🤖 ASSISTANT: The address is 123 Main Street.
    [14:23:30] 🎤 HUMAN: And your phone number?
    [14:23:30] 🤖 ASSISTANT: The phone number is 555-0123.
    [14:23:35] 🎤 HUMAN: Perfect! That'll be $18.99. We'll have it delivered in about 30 minutes.
    [14:23:40] 🤖 ASSISTANT: That sounds great! Thank you so much.
    [14:23:42] 🎤 HUMAN: You're welcome! Have a great day.

Pizza ordered successfully! 🍕

📚 Quick Context for the Uninitiated

VoIP (Voice over IP) is how you make phone calls over the internet instead of traditional phone lines. SIP (Session Initiation Protocol) is the language these systems speak to connect calls. Think of it as HTTP but for phone calls.

Fritz!Box is a popular German router/modem that happens to have a built-in phone system (PBX). If you have one, you already have everything you need to make VoIP calls - this tool just connects to it. Outside Germany, you might know similar devices from other brands, or use dedicated VoIP services like Asterisk, 3CX, or cloud providers.

MCP (Model Context Protocol) is Anthropic's standard for connecting AI assistants like Claude to external tools and services. It's what lets MCP clients actually do things instead of just talking about them.

🚀 What This Enables

• 🔌 MCP Server - Use directly in Claude Code or any MCP client (most popular usage)
• 🖥️ CLI Tool - Command-line interface for direct phone calls
• 📚 TypeScript API - Programmatic library for building voice applications

Built as a bridge between OpenAI's Real-Time Voice API and VoIP networks, with multiple codec support (G.722, G.711), and expanded SIP protocol support for broad VoIP compatibility. Compatible with the latest gpt-realtime model released August 28, 2025.

🏗️ System Architecture

graph TB
    subgraph "User Interface"
        A[Claude Code/MCP Client]
        B[CLI Tool]
        C[TypeScript API]
    end
    
    subgraph "CallCenter.js Core"
        D[MCP Server]
        E[VoiceAgent]
        F[Call Brief Processor<br/>o3-mini model]
    end
    
    subgraph "Communication Layer"
        G[SIP Client<br/>Provider Support]
        H[Audio Bridge<br/>RTP Streaming]
    end
    
    subgraph "Audio Processing"
        I[G.722 Codec<br/>16kHz Wideband]
        J[G.711 Codec<br/>8kHz Fallback]
    end
    
    subgraph "External Services"
        K[OpenAI Real-Time API<br/>gpt-realtime model]
        L[VoIP Network<br/>Fritz!Box/Asterisk/etc]
    end
    
    A --> D
    B --> E
    C --> E
    D --> E
    E --> F
    E --> G
    E --> H
    F --> K
    G --> L
    H --> I
    H --> J
    H --> K
    
    style F fill:#e1f5fe
    style K fill:#fff3e0
    style L fill:#f3e5f5

⚠️ Vibe-coded project! Developed and tested on Fritz!Box (a German router with built-in VoIP) only. Other provider configs are research-based but untested. YMMV, no warranties. See disclaimer below.

🔌 MCP Client Integration (Most Popular!)

Perfect for when your coding agent needs to call library authors to complain about their documentation! 😄

Quick Setup

# Add to Claude Code with one command:
claude mcp add --env SIP_USERNAME=your_actual_extension \
  --env SIP_PASSWORD="your_actual_password" \
  --env SIP_SERVER_IP=192.168.1.1 \
  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
  --env USER_NAME="Your Actual Name" \
  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp

Then just ask your MCP Client to make calls:

"Can you call the pizza place and order a large pepperoni? My number is 555-0123."

Your MCP Client will automatically handle the entire conversation using the AI Voice Agent! 🤖📞

✨ Key Features

• 🎙️ Multiple Codec Support: G.722 wideband (16kHz) + G.711 fallback for broad compatibility
• 🧩 Compiler-Free WASM Codec: Ships with a prebuilt G.722 WebAssembly module so npx users get wideband audio without installing build tools (native addon still available for max performance)
• 🤖 AI-Powered Conversations: Uses OpenAI's Real-Time Voice API with the latest gpt-realtime model (released August 28, 2025) for actual calls, with o3-mini model for instruction generation
• 🌍 Automatic Language Detection: Intelligently detects conversation language from call briefs and configures transcription accordingly
• 🎭 Auto Voice Selection: New 'auto' mode where o3-mini selects optimal voice based on call context (formality, industry, goals)
• 🔊 Voice Characteristics: Full support for all 10 OpenAI Realtime API voices with gender and personality awareness
• 🌐 Expanded SIP Support: Configurations for common SIP providers (Fritz!Box tested, others experimental)
• 🔧 Smart Configuration: Auto-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: Integrate with MCP clients like Claude Code
• 📚 TypeScript API: Programmatic library for building voice applications
• 📝 Call Brief Processing: Natural language call instructions using o3-mini model with structured JSON output
• 🎵 Optional Call Recording: Stereo WAV recording with caller/AI separation

🚀 Quick Start

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

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=auto
EOF

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

Note: High-quality G.722 audio ships as a prebuilt WebAssembly module, so npx works even on machines without compilers. If you want the faster native addon instead, run npm run build:native (or npm run build:all) after cloning.

Option 2: Local Installation

Prerequisites

• Node.js 20+
• (Optional) Python 3.x + C/C++ build tools — only needed if you plan to rebuild the native addon instead of using the bundled WebAssembly codec
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Visual Studio Build Tools
  • Linux: build-essential package
• OpenAI API key

Note: The prebuilt WebAssembly codec already provides wideband G.722 audio out of the box. Rebuilding the native addon is optional and mainly useful for squeezing out a little more performance.

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

🎯 Usage Options

1. MCP Server (Claude Code Integration) ⭐

Most popular usage - integrates with Claude Code for seamless AI-powered calling. Perfect for when your coding agent needs to call library authors to complain about their documentation! 😄

Quick Setup with npx (Recommended)

Option 1: Using MCP Client CLI (Easiest)

# Replace with your ACTUAL credentials before running:
claude mcp add --env SIP_USERNAME=your_actual_extension \
  --env SIP_PASSWORD="your_actual_password" \
  --env SIP_SERVER_IP=192.168.1.1 \
  --env OPENAI_API_KEY="sk-your_actual_openai_key" \
  --env USER_NAME="Your Actual Name" \
  -- callcenter.js npx -- github:gerkensm/callcenter.js-mcp --mcp

⚠️ Important: Replace the placeholder values with your actual SIP credentials and OpenAI API key, or the server will fail to connect.

Option 2: Manual Configuration

Configure in Claude Code's MCP settings to automatically pull from GitHub:

{
  "mcpServers": {
    "callcenter.js": {
      "command": "npx",
      "args": ["github:gerkensm/callcenter.js-mcp", "--mcp"],
      "env": {
        "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"
      }
    }
  }
}

Alternative: Local Installation

For local development or if you prefer local installation:

npm start --mcp

Or configure Claude Code with local installation:

{
  "mcpServers": {
    "callcenter.js": {
      "command": "node",
      "args": ["dist/cli.js", "--mcp"],
      "cwd": "/path/to/voip-agent"
    }
  }
}

Available MCP tools:

• simple_call - Make calls with automatic instruction generation
• advanced_call - Make calls with granular parameter control

Example usage in MCP Client:

You: "Can you call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm? My name is John Doe."

MCP Client: I'll call Bocca di Bacco restaurant

…