Callcenter.js MCP

🚀 CallCenter.js MCP + CLI

CallCenter.js MCP + CLI 是一个 MCP 服务器、命令行工具和 API，借助 VoIP 技术代表你拨打电话。只需告知 Claude 你的需求，它就能自动拨打电话并处理对话。该工具本质上是一个 MCP 服务器，在 OpenAI 的实时语音 API 和你的 VoIP 连接之间架起桥梁，代表你拨打电话。

🚀 快速开始

选项 1：使用 npx 立即运行（无需安装） ⚡

这是体验该工具的最快方式：

# 设置环境变量（或创建 .env 文件）
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"

# 直接从 GitHub 运行（无需安装！）
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

或者使用 .env 文件：

# 创建 .env 文件
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

# 从 GitHub 运行（自动加载 .env 文件）  
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"

注意：首次运行时，若你未安装 C++ 构建工具，可能会显示构建警告，但使用 G.711 编解码器回退仍可正常工作（标准电话音质）。若想获得更好的音频质量，建议先安装构建工具以启用 G.722 宽带编解码器。

选项 2：本地安装

前提条件

• Node.js 20+
• Python 3.x + 构建工具（用于 G.722 宽带音频，可显著提升通话质量）
  • macOS：安装 Xcode 命令行工具 (xcode-select --install)
  • Windows：安装 Visual Studio 构建工具
  • Linux：安装 build-essential 包
• OpenAI API 密钥

注意：若未安装构建工具，系统将自动回退到 G.711（标准电话音质）。G.722 编解码器的带宽是 G.711 的两倍，可实现更清晰、自然的对话。

安装步骤

# 克隆并安装
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# 复制示例配置文件
cp config.example.json config.json

配置

编辑 config.json 文件，填入你的设置：

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

✨ 主要特性

• 🎙️ 多编解码器支持：支持 G.722 宽带（16kHz）和 G.711 回退编解码器，确保广泛的兼容性。
• 🤖 AI 驱动的对话：利用 OpenAI 的实时语音 API 进行实际通话，并使用 o3-mini 模型（OpenAI 的推理模型）生成指令。
• 🌐 扩展的 SIP 支持：为常见的 SIP 提供商提供配置（已在 Fritz!Box 上测试，其他提供商为实验性支持）。
• 🔧 智能配置：自动检测提供商要求并优化设置。
• 📞 企业级支持：支持高级 SIP 功能（STUN/TURN、会话定时器、传输回退）。
• 🔄 强大的连接管理：具备自动重连功能和智能错误处理机制。
• ✅ 内置验证：全面的配置验证和网络测试。
• 🎯 提供商配置文件：为流行的 SIP 系统提供预配置设置。
• 🔌 MCP 服务器：可与 Claude Code 和其他 MCP 客户端集成。
• 📚 TypeScript API：提供用于构建语音应用程序的编程库。
• 📝 通话摘要处理：使用 o3-mini 模型处理自然语言通话指令。
• 🎵 可选的通话录音：支持立体声 WAV 录音，可分离主叫方和 AI 的声音。

📦 安装指南

选项 1：使用 npx 立即运行（无需安装） ⚡

# 设置环境变量（或创建 .env 文件）
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"

# 直接从 GitHub 运行（无需安装！）
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant for reservation" --user-name "Your Name"

或者使用 .env 文件：

# 创建 .env 文件
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

# 从 GitHub 运行（自动加载 .env 文件）  
npx github:gerkensm/callcenter.js-mcp call "+1234567890" --brief "Call restaurant"

选项 2：本地安装

前提条件

• Node.js 20+
• Python 3.x + 构建工具（用于 G.722 宽带音频，可显著提升通话质量）
  • macOS：安装 Xcode 命令行工具 (xcode-select --install)
  • Windows：安装 Visual Studio 构建工具
  • Linux：安装 build-essential 包
• OpenAI API 密钥

安装步骤

# 克隆并安装
git clone https://github.com/gerkensm/callcenter.js-mcp
cd callcenter.js-mcp
npm install

# 复制示例配置文件
cp config.example.json config.json

💻 使用示例

基础用法

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

// 简单通话示例
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}`);

高级用法

// 高级用法：使用代理实例
const agent = await createAgent('config.json');

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

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

📚 详细文档

1. MCP 服务器（Claude Code 集成） ⭐

这是最常用的用法，可与 Claude Code 无缝集成，实现 AI 驱动的通话。非常适合让你的编码代理联系库作者，反馈文档问题！😄

使用 npx 快速设置（推荐）

选项 1：使用 Claude Code CLI（最简单）

# 运行前请替换为你的实际凭证：
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

⚠️ 重要提示：请将占位符值替换为你的实际 SIP 凭证和 OpenAI API 密钥，否则服务器将无法连接。

选项 2：手动配置 在 Claude Code 的 MCP 设置中进行配置，自动从 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"
      }
    }
  }
}

替代方案：本地安装

若你需要进行本地开发或更喜欢本地安装方式：

npm start --mcp

或者使用本地安装进行配置：

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

可用的 MCP 工具：

• simple_call - 自动生成指令进行通话
• advanced_call - 可对参数进行精细控制的通话

在 Claude Code 中的使用示例：

"Can you call Bocca di Bacco restaurant and book a table for 2 people tonight at 7:30pm? My name is John Doe." Claude 将自动使用 MCP 服务器为你拨打电话！

2. 命令行界面

当你需要通过 curl -X POST 摆脱社交义务，或者实现 ai-human-sort 算法时，命令行界面是你的理想选择！😄

💡 建议使用 --brief 而非 --instructions 以获得更好的效果！ --brief 选项使用 OpenAI 的 o3-mini 模型，根据你的简单描述生成复杂的指令，而 --instructions 则直接将你的文本发送到实时语音 API。由于实时语音 API 更注重速度而非复杂性，因此 --brief 通常能产生更好的通话效果。

# ✅ 推荐：使用 brief 实现自然语言目标
npm start call "+1234567890" --brief "Call the restaurant and book a table for 2 at 7pm tonight" --user-name "John Doe"

# ✅ 推荐：brief 适用于任何类型的通话
npm start call "+1234567890" --brief "Call to check appointment availability for John Doe"

# ⚠️ 仅在需要特定自定义行为时使用 instructions
npm start call "+1234567890" --instructions "You must follow this exact script: Say hello, ask for manager, then hang up"

# 其他使用 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"

CLI 选项

npm start call <number> [options]

Options:
  -c, --config <path>           Configuration file path (default: config.json)
  -d, --duration <seconds>      Maximum call duration in seconds (default: 600)
  -v, --verbose                 Verbose mode - show all debug information
  -q, --quiet                   Quiet mode - show only transcripts, errors, and warnings
  --log-level <level>           Set log level (quiet|error|warn|info|debug|verbose) (default: info)
  --no-colors                   Disable colored output
  --no-timestamp                Disable timestamps in logs
  --record [filename]           Enable stereo call recording (optional filename)
  --brief <text>                Call brief to generate instructions from (RECOMMENDED)
  --instructions <text>         Direct AI instructions (use only for specific custom behavior)
  --user-name <name>            Your name for the AI to use when calling
  --help                        Display help information

3. 编程 API

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

// 简单通话示例
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}`);

// 高级用法：使用代理实例
const agent = await createAgent('config.json');

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

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

🔧 技术细节

编解码器优先级和协商

1. G.722（首选） - 16kHz 宽带，提供卓越的语音质量。
2. G.711 μ-law（回退） - 8kHz 窄带，具备普遍的兼容性。
3. G.711 A-law（回退） - 8kHz 窄带，是欧洲标准。

G.722 实现

• 原生 C++ 插件：确保最佳性能。
• 基于参考实现：源自 CMU 和 Sippy Software。
• 自动回退：若编译失败，自动回退到 G.711。
• 实时编码/解码：低延迟。

可选的通话录音

• 立体声 WAV 格式：主叫方声音在左声道，AI 声音在右声道。
• 可选的文件名指定。
• 同步音频流：确保完美对齐。
• 高质量 PCM 录音：以原生采样率进行录制。

测试音频质量

# 测试编解码器可用性
npm run test:codecs

# 若需要，不使用 G.722 进行构建
npm run build:no-g722

AI 通话摘要处理

重要性：实时语音 API 需要更完善的指令

OpenAI 的实时语音 API 优化了速度，但在处理复杂的目标导向任务时，若没有非常具体的指令，可能会遇到困难。以下是具体问题：

• ❌ 效果不佳的情况：

# 模糊的摘要 - 实时语音 API 会感到困惑且缺乏重点
npm start call "+1234567890" --brief "Call the restaurant and book a table"

• ❌ 繁琐且易出错的情况：

# 每次手动编写详细指令
npm start call "+1234567890" --instructions "You are calling on behalf of John Doe to make a restaurant reservation for 2 people at Bocca di Bacco for tonight at 7pm. You should start by greeting them professionally, then clearly state your purpose. Ask about availability for 7pm, and if not available, ask for alternative times between 6-8pm. Confirm the booking details including date, time, party size, and get a confirmation number if possible. If you reach voicemail, leave a professional message with callback information..."

• ✅ 效果出色的情况：

# 简单的摘要 - o3 模型生成复杂的指令
npm start call "+1234567890" --brief "Call Bocca di Bacco and book a table for 2 at 7pm tonight" --user-name "John Doe"

工作原理

系统使用 OpenAI 的 o3-mini 推理模型（最新的小型推理模型，智能且快速），根据你的简单摘要自动生成详细、复杂的指令。o3-mini 模型的工作流程如下：

1. 分析摘要：理解目标。
2. 创建对话状态：构建流程逻辑。
3. 生成特定指令：针对通话的每个阶段。
4. 处理边缘情况：如语音信箱、异议和替代方案。
5. 调整语言和语气：根据上下文进行调整。
6. 提供回退策略：应对意外情况。

前后对比示例

你的简单输入：

"Call Bocca di Bacco and book a table for 2 at 7pm tonight"

o3-mini 生成的内容（节选）：

## 个性与语气
身份：我是代表 John Doe 进行餐厅预订的助理。
任务：我负责为今晚 7 点在 Bocca di Bacco 预订 2 人的餐桌。
语气：专业、热情且尊重。

## 指令
1. 立即开启对话：“您好，我是代表 John Doe 打电话的助理。”
2. 重复关键信息：确认时间和细节。
3. 处理异议：礼貌回应并提供 6 - 8 点之间的替代时间。
...

## 对话状态
[
  {
    "id": "1_greeting",
    "description": "问候并介绍通话目的",
    "instructions": ["自我介绍为助理", "立即提及预订请求"],
    "examples": ["您好，我是代表 John Doe 打电话的助理。我想为今晚 7 点预订 2 人的餐桌。"]
  }
]

自动调整

o3-mini 摘要处理器会自动：

• 检测语言：根据你的摘要，以相应语言生成指令。
• 创建对话流程：包含逻辑状态和转换。
• 处理文化背景：适应不同国家的餐厅文化（如德国、美国、日本）。
• 生成合适的示例：使用真实的短语（无占位符）。
• 提供语音信箱脚本：当无人接听时使用。
• 规划应对异议的策略：提供替代解决方案。

使用建议

• 95% 的通话使用 --brief：更便捷且效果更佳。
• 仅在需要特定自定义行为时使用 --instructions。
• 摘要处理：适用于预订、预约、商务通话、客户服务等场景。
• 直接指令：适用于高度专业化的场景、测试或已完善提示信息的情况。

高级功能

智能连接管理

• 自动重连：采用指数退避算法，并针对不同提供商进行错误处理。
• 传输回退：根据情况自动从 UDP 切换到 TCP 再到 TLS。
• 提供商感知的错误恢复：针对 Fritz Box、Asterisk 和 Cisco 等不同提供商采用不同的恢复策略。
• 网络变化处理：适应网络连接的变化。

增强的 SIP 协议支持

• STUN/TURN 集成：为云部署和企业部署提供 NAT 穿透功能。
• 会话定时器（RFC 4028）：确保长时间通话的连接稳定性。
• PRACK 支持（RFC 3262）：为企业系统提供可靠的临时响应。
• 多传输方式：支持 UDP、TCP、TLS，并具备智能回退机制。

配置智能

• 提供商自动检测：根据 SIP 域名/IP 识别提供商。
• 需求验证：确保满足所有提供商特定的需求。
• 网络测试：对 SIP 服务器和 STUN 服务器进行实际的连接测试。
• 优化建议：提供可操作的建议，以提升性能。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

第三方组件

• G.722 编解码器：采用公共领域和 BSD 许可的实现。
• SIP 协议：基于 sipjs-udp（MIT 许可）。
• 依赖项：采用各种开源许可证（详见 package.json）。

📋 配置验证

在拨打电话之前，请验证你的配置：

# 基本验证
npm run validate config.json

# 详细验证，包含网络连接测试
npm run validate:detailed

# 获取针对问题的具体修复建议
npm run validate:fix

# 测试不同提供商的示例配置
npm run validate:fritz-box       # AVM Fritz!Box
npm run validate:asterisk        # Asterisk PBX  
npm run validate:cisco           # Cisco CUCM
npm run validate:3cx             # 3CX Phone System
npm run validate:generic         # 通用 SIP 提供商

验证器将检查以下内容：

• ✅ 配置语法和必填字段
• ✅ 特定提供商的要求
• ✅ 与 SIP 服务器的网络连接
• ✅ STUN 服务器的可达性
• ✅ 编解码器可用性（G.722/G.711）
• ✅ 提供商兼容性得分

🌐 SIP 提供商兼容性

✅ 实际测试过的提供商

• AVM Fritz!Box - 德国路由器品牌，内置 VoIP/SIP 电话系统 ✅ 可用（唯一实际测试过的提供商）

🤷 基于推测的配置（有根据的猜测）

• Asterisk PBX - 开源 PBX（FreePBX、Elastix 等） 🤷 未测试
• Cisco CUCM - 企业统一通信系统 🤷 未测试
• 3CX Phone System - 流行的商业 PBX 🤷 未测试
• 通用 SIP 提供商 - 符合标准的 SIP 中继 🤷 未测试

🔧 特定提供商的功能

提供商配置文件基于研究和文档，而非实际测试：

提供商	传输方式	NAT 穿透	会话定时器	PRACK	保活机制
Fritz Box	UDP	无需	可选	禁用	重新注册
Asterisk	UDP/TCP	STUN	支持	可选	OPTIONS ping
Cisco CUCM	首选 TCP	需要 STUN	必需	必需	OPTIONS ping
3CX	TCP/UDP	STUN	支持	可选	重新注册

📝 配置示例

项目包含所有主要提供商的即用型配置：

• config.example.json - AVM Fritz!Box（家庭/中小企业默认配置）
• config.asterisk.example.json - Asterisk PBX 高级功能配置
• config.cisco.example.json - Cisco CUCM 企业级设置
• config.3cx.example.json - 3CX 电话系统 配置
• config.generic.example.json - 通用 SIP 提供商 模板

🛠️ 开发与测试

构建命令

# 完整构建（TypeScript + 原生插件）
npm run build

# 分别构建组件  
npm run build:native    # 仅构建原生 G.722 插件
npm run build:ts       # 仅进行 TypeScript 编译

# 开发模式，支持热重载
npm run dev

# 清理所有构建产物
npm run clean

配置测试

# 验证任何配置文件
npm run validate path/to/config.json

# 使用不同提供商进行测试
npm run validate -- --provider asterisk config.json

# 获取详细的网络诊断信息
npm run validate -- --detailed --network config.json

# 显示问题的修复建议
npm run validate -- --fix-suggestions config.json

项目结构

src/
├── voice-agent.ts          # 主协调模块，与连接管理器交互
├── connection-manager.ts   # 智能连接处理和重连机制
├── sip-client.ts          # 增强的 SIP 协议，支持不同提供商
├── audio-bridge.ts        # RTP 流和编解码器管理
├── openai-client.ts       # OpenAI 实时语音 API 集成
├── call-brief-processor.ts # o3-mini 模型通话摘要处理
├── mcp-server.ts          # MCP（模型上下文协议）服务器
├── validation.ts          # 配置验证引擎
├── config.ts             # 增强的配置加载，支持提供商配置文件
├── logger.ts             # 全面的日志记录，捕获通话记录
├── index.ts              # 主编程 API 导出
├── providers/
│   └── profiles.ts       # 特定提供商的配置数据库
├── testing/
│   └── network-tester.ts # 实际的网络连接测试
├── codecs/               # 编解码器抽象层
│   ├── g722.ts          # G.722 宽带实现
│   └── g711.ts          # G.711 回退编解码器
└── cli.ts               # 命令行界面

scripts/
└── validate-config.js   # 全面的验证 CLI 工具

config.*.example.json    # 特定提供商的示例配置

📊 验证与诊断

内置的验证系统提供全面的分析：

配置报告示例

🔍 CallCenter.js 配置验证器

📋 提供商: AVM Fritz!Box（自动检测）
🎯 提供商兼容性得分: 100%

✅ 配置有效，可立即使用！

🌐 网络连接:
   ✅ SIP 服务器: 可达（延迟 12ms）
   ✅ G.722 编解码器: 可用，可提供高质量音频

💡 优化建议:
   💡 G.722 宽带编解码器可用（已启用）
   💡 延迟极低 - 本地网络性能最优

🚀 下一步: npm start call "<number>"

网络诊断

• 实际的 SIP 服务器测试：进行实际的 UDP/TCP 连接测试。
• STUN 服务器验证：测试 NAT 穿透能力。
• 延迟测量：评估网络性能。
• 特定提供商的建议：根据检测到的问题提供针对性建议。

🔧 故障排除

配置问题

1. 首先运行验证：

npm run validate:detailed

2. 检查提供商兼容性：

npm run validate -- --provider fritz-box config.json

3. 获取特定的修复建议：

npm run validate:fix

网络连接问题

• Fritz Box：通常在本地网络上使用 UDP 即可正常工作。
• 云/企业环境：可能需要 STUN 服务器进行 NAT 穿透。
• 防火墙问题：确保 SIP 端口（5060）和 RTP 端口开放。

音频质量问题

1. 验证 G.722 是否可用：

npm run test:codecs

2. 检查日志中的编解码器协商情况：

✅ 所选编解码器: PT 9 (G722/8000)

3. 网络问题：高延迟/数据包丢失会影响音频质量。

构建问题

1. 原生编译失败：

# 先安装构建工具，然后：
npm run build:no-g722  # 仅回退到 G.711

2. 特定提供商的问题：查看针对你所使用提供商的验证建议。

MCP 集成问题

1. 服务器无法启动：

# 检查端口冲突或配置问题
npm start --mcp

2. Claude Code 无法连接：

• 验证 Claude Code 设置中的 MCP 服务器配置。
• 确保工作目录路径正确。
• 确保服务器正在运行且可访问。

⚠️ 重要免责声明

本项目是一个基于创意的项目！🚀 这意味着：

• ✅ 在 Fritz!Box 上可用 - 这是实际测试过的环境。
• 🤷 其他提供商 - 尽力使其更具通用性，但无法保证。
• 🤷 高级功能 - 基于研究提出的想法，但实际效果未知。
• ⚠️ 效果因人而异 - 你的设置可能与我的不同。
• ⚠️ 无保修 - 请自行承担使用风险。

对你的影响

• Fritz Box 用户：应该可以正常使用！✅
• 其他提供商用户：配置文件是基于研究的有根据的猜测，可能有效，也可能无效。
• 企业用户：尝试添加了重要的功能，但无法保证其正确性。
• 问题与拉取请求：欢迎提交拉取请求，但无法保证能修复无法复现或测试的问题。

贡献建议

• ✅ 在你的环境中测试：并分享使用情况。
• ✅ 分享可用的配置：如果你成功让其他提供商正常工作。
• ✅ 修复问题：并提交拉取请求。
• ✅ 反馈假设错误：如果你发现对提供商的假设存在错误。

验证工具可能有助于调试问题，但实际能否拨打电话才是真正的测试。

🤝 贡献指南

1. 分叉仓库。
2. 创建功能分支。
3. 为新提供商添加/更新验证。
4. 使用 npm run validate:detailed 进行测试。
5. 提交拉取请求。

📞 支持

• 配置问题：使用 npm run validate:detailed 进行诊断。
• 提供商支持：查看上述兼容性矩阵。
• 构建问题：参考故障排除部分。
• 功能请求：可以在 GitHub 上创建问题，但近期可能不会得到关注。更欢迎提交拉取请求！

---

准备好开始了吗？ 复制一个示例配置，运行 npm run validate:detailed，然后开始进行 AI 驱动的语音通话！🚀