1. 项目概述Famulor MCP Server让AI助手直接打电话如果你和我一样经常在ChatGPT、Claude或者Cursor里和AI对话处理各种任务那你有没有想过能不能让这些AI助手直接帮你打个电话比如让AI帮你预约个服务、做个简单的客户回访或者处理一些基础的电话沟通听起来像是科幻电影里的场景但现在通过一个叫**Model Context ProtocolMCP**的协议这已经变成了现实。今天要聊的就是一个把这种想象落地的具体项目Famulor MCP Server。简单来说它是一个“翻译官”或者说“适配器”。Famulor本身是一个专业的语音AI平台能创建会打电话的AI助手。而这个MCP服务器就是把Famulor平台的所有能力——打电话、管理助手、查看通话记录——打包成一套标准化的工具然后“喂”给你常用的AI客户端。这样一来你不需要离开熟悉的ChatGPT或Claude界面直接在里面输入一句“帮我给张三打个电话确认一下明天的会议时间”AI就能理解你的意图调用背后的Famulor服务真的把电话拨出去。这个项目的核心价值在于无缝集成和降低使用门槛。你不用去学习Famulor复杂的后台操作也不用自己写代码调用API。你只需要像安装一个插件一样配置好这个MCP服务器然后就能用最自然的对话方式指挥AI去完成电话任务。这对于需要大量外呼的销售团队、需要做自动化客户服务的公司或者只是想体验一下AI电话的开发者来说都是一个非常酷且实用的工具。接下来我会从为什么需要它、怎么把它跑起来、以及实际使用中会遇到哪些坑这几个方面带你彻底玩转这个项目。2. 核心原理与架构拆解MCP如何成为AI的“手和脚”在深入配置之前我们得先搞明白MCP到底是什么以及Famulor MCP Server在这个生态里扮演什么角色。这能帮你更好地理解后续的所有操作甚至在出问题时知道该从哪里排查。2.1 Model Context Protocol (MCP)AI的标准化扩展接口你可以把MCP想象成电脑的USB接口。在MCP出现之前每个AI应用如ChatGPT、Claude如果想连接外部工具比如查数据库、发邮件、控制智能家居都需要开发者为其量身定制一套连接方案这就像每个外设都需要一个专属的、形状各异的接口非常麻烦。MCP的出现就是为了定义一套标准的“USB协议”。它规定了AI客户端ChatGPT Desktop, Claude Desktop和外部工具服务器比如我们这个Famulor MCP Server之间应该如何通信、交换数据。只要工具服务器按照MCP的规范来“说话”那么所有支持MCP的AI客户端就都能识别并使用它。MCP的核心通信模式主要有两种stdio标准输入输出这是最经典、兼容性最好的方式。AI客户端直接启动一个本地进程我们的Node.js服务器两者通过命令行标准输入输出流进行JSON格式的对话。这种方式完全在本地运行数据不出本地安全性高。Claude Desktop目前主要支持这种方式。SSEServer-Sent Events这是一种基于HTTP的协议客户端通过一个长连接监听服务器发送的事件流。这种方式适合服务器部署在远端云上客户端通过URL连接。它的好处是无需在本地运行服务器进程开箱即用。ChatGPT Desktop和Cursor对这种方式支持良好。Famulor MCP Server同时支持这两种模式这也是它设计上的一个亮点给了用户最大的灵活性。2.2 Famulor MCP Server的架构三层桥接这个项目的代码结构清晰地反映了一个三层桥接的架构[AI客户端 (ChatGPT/Claude/Cursor)] ⬆⬇ (通过MCP协议通信) [Famulor MCP Server (本项目)] ⬆⬇ (通过HTTPS调用REST API) [Famulor云端语音AI平台]协议转换层src/server.ts这是项目的“大脑”。它启动一个MCP服务器实例按照MCP的规范向AI客户端宣告自己有哪些“工具”Tools可用比如make_call,list_assistants。当AI客户端想要使用某个工具时它会通过MCP协议发送一个结构化的请求过来。工具实现层src/tools/这是项目的“肌肉”。server.ts接收到请求后会根据工具名称路由到对应的工具函数。例如tools/calls.ts里的makeCall函数。这个函数负责将MCP格式的请求参数转换成Famulor官方API所期望的格式。API客户端层src/auth/famulor.ts这是项目的“手和脚”。它封装了所有与Famulor云平台通信的细节包括使用用户的API Key进行身份认证、处理HTTP请求、解析响应和错误。工具层调用这里提供的方法最终完成对云端真实服务的操作。为什么需要这个服务器因为Famulor的原始API是给程序员用的返回的是JSON数据。而AI助手LLM需要的是更高层次的、语义化的“工具”描述。这个MCP服务器的工作就是把POST https://api.famulor.io/v1/calls这样的API包装成make_call(assistant_id, phone_number)这样一个AI能理解、能调用的函数。2.3 关键设计安全性处理安全性是这个项目考虑的重点也是你在使用时必须注意的。API Key隔离你的Famulor API Key永远不会发送给这个MCP服务器的开发者。它只存在于两个地方1) 你本地配置文件mcp.json里2) 你本地运行的Node.js进程的内存中。如果你使用在线托管服务器你的API Key会在每个请求的HTTP Header中发送但这仅限于你和托管服务器之间类似于你使用任何其他在线API。配置即代码所有工具的定义名称、描述、参数schema都硬编码在TypeScript中。这意味着AI客户端在初始化连接时就能一次性获取所有工具的“说明书”知道该怎么调用参数是什么类型。这保证了交互的强类型和可靠性。错误处理与重试在famulor.ts客户端中通常会包含对网络错误、API限流、认证失败等情况的处理逻辑并以MCP标准格式返回错误信息让AI客户端能清晰地告知用户问题所在。理解了这些你就会明白后续的安装配置本质上就是在为你喜欢的AI客户端“安装一个驱动程序”告诉它“嘿这里有一个新的USB设备MCP服务器它提供了打电话的工具这是连接方式stdio路径或SSE URL和密码API Key。”3. 实战部署两种方案详解与避坑指南纸上得来终觉浅绝知此事要躬行。接下来我们分步拆解如何让这个MCP服务器真正为你所用。你有两条主要路径使用官方托管服务最快或本地自行部署最可控。我会详细说明每一步并附上我踩过坑后总结的注意事项。3.1 准备工作获取通行证API Key无论选择哪种部署方式你都需要一把“钥匙”来访问Famulor平台的服务这就是API Key。访问Famulor平台打开 Famulor API Keys管理页面 。你需要注册并登录一个Famulor账号。通常平台会提供免费额度供开发者测试。创建API Key在页面中找到创建新密钥的按钮通常是“Create New API Key”或“ New Key”。妥善保存创建后平台会显示一次你的密钥字符串。务必立即复制并保存到安全的地方比如密码管理器。因为它一旦消失就无法再次查看只能重新生成。这个密钥将拥有你账户对应的权限请像保护密码一样保护它。注意在测试时你可以使用平台提供的免费额度或测试密钥。但如果用于生产环境务必在Famulor后台仔细查看该密钥的权限范围遵循最小权限原则。3.2 方案一使用在线托管服务器推荐新手这是最快捷的入门方式无需安装Node.js或克隆代码库。优点开箱即用免维护适合快速体验和大多数稳定使用场景。缺点依赖第三方服务可用性自定义程度低。核心步骤就两步得到SSE连接地址托管服务器的SSE端点固定为https://mcp.famulor.io/sse。在AI客户端中配置在你的ChatGPT Desktop、Cursor等工具的MCP设置里添加一个指向该URL的服务器配置并填入你的API Key。不同客户端的配置差异这是关键对于ChatGPT Desktop和大多数支持HTTP/SSE的客户端 配置格式相对统一直接在mcp.json的env字段里设置API Key。{ mcpServers: { famulor: { url: https://mcp.famulor.io/sse, env: { FAMULOR_API_KEY: 你的-api-key-粘贴在这里 } } } }对于Cursor Cursor的配置方式类似但它要求将API Key放在HTTP Header中并且需要加上Bearer前缀。{ mcpServers: { famulor: { type: http, url: https://mcp.famulor.io/sse, headers: { Authorization: Bearer 你的-api-key-粘贴在这里 } } } }重要提示Bearer后面必须有一个空格这是HTTP Bearer Token认证的标准格式。很多人在这一步配置失败就是因为漏了这个空格。对于Claude Desktop特别注意 截至目前Claude Desktop仅支持通过本地command启动的MCP服务器不支持直接配置HTTP/SSE URL。这意味着你无法在Claude Desktop中直接使用在线的https://mcp.famulor.io/sse地址。如果你想在Claude中使用必须采用下面的“方案二本地部署”。配置完成后完全重启你的AI客户端彻底关闭再打开让配置生效。然后你就可以在对话中尝试使用Famulor的工具了。3.3 方案二本地部署服务器适合开发者与定制如果你想深入了解、自定义功能或者你主要使用Claude Desktop那么本地部署是必须的。第一步环境准备安装Node.js确保你的系统安装了Node.js且版本 20.0.0。在终端运行node --version检查。如果版本过低去 Node.js官网 下载安装。获取项目代码打开终端运行以下命令克隆仓库并进入目录。git clone https://github.com/bekservice/Famulor-MCP.git cd Famulor-MCP第二步安装与构建安装依赖项目使用TypeScript编写需要安装编译器和依赖。npm install如果网络较慢可以考虑配置npm镜像源。构建项目将TypeScript代码编译成JavaScript。npm run build成功后你会看到项目根目录下生成了一个dist文件夹里面包含了可运行的index.js。避坑指南权限问题在Linux/macOS系统如果遇到权限错误可以尝试在命令前加sudo但更推荐的方法是修复npm的全局安装权限。依赖安装失败检查网络或尝试删除node_modules文件夹和package-lock.json文件后重新运行npm install。构建错误确保TypeScript版本兼容。如果是从旧版本升级而来尝试npm cache clean --force然后重新安装。第三步配置AI客户端以Claude Desktop为例这是最关键的一步需要告诉AI客户端如何启动我们这个本地服务器。找到配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json(通常位于C:\Users\你的用户名\AppData\Roaming\Claude\)Linux:~/.config/Claude/claude_desktop_config.json编辑配置文件用文本编辑器如VSCode、Notepad打开这个文件。如果文件不存在就创建一个。添加MCP服务器配置在JSON文件中添加mcpServers部分。请务必替换以下示例中的路径和API Key。{ mcpServers: { famulor: { command: node, args: [ /绝对/路径/到/Famulor-MCP/dist/index.js ], env: { FAMULOR_API_KEY: 你的-api-key-粘贴在这里 } } } }路径填写注意事项极易出错必须是绝对路径不能使用./dist/index.js这样的相对路径。你必须提供从根目录开始的完整路径。路径分隔符macOS/Linux: 使用正斜杠/。例如/Users/zhangsan/Projects/Famulor-MCP/dist/index.jsWindows: 可以使用正斜杠/也可以使用双反斜杠\\。例如C:/Users/zhangsan/Documents/Famulor-MCP/dist/index.js或C:\\Users\\zhangsan\\Documents\\Famulor-MCP\\dist\\index.js。不推荐使用单反斜杠因为在JSON字符串中它是转义字符。如何获取绝对路径macOS/Linux: 在终端中进入Famulor-MCP目录运行pwd命令会打印出当前绝对路径然后在其后加上/dist/index.js。Windows (PowerShell): 在Famulor-MCP目录下打开PowerShell运行pwd同样会得到路径然后替换掉反斜杠或使用双反斜杠。重启客户端必须完全关闭Claude Desktop再重新打开仅刷新界面是没用的MCP配置只在启动时加载。第四步验证连接重启Claude后你可以通过一些迹象判断是否成功在Claude的输入框里尝试输入“你能用什么工具”或者“列出你的工具”。如果配置成功Claude的回复中应该会提及Famulor相关的工具如make_call,get_assistants等。直接尝试指令“列出我的Famulor助手”。如果成功Claude会调用工具并返回你在Famulor平台创建的助手列表。4. 核心功能工具详解与使用心法配置成功只是开始真正发挥威力在于如何使用这些工具。Famulor MCP Server暴露了多达二十几个工具覆盖通话、助手、对话、营销活动、线索、短信等全流程。这里我挑几个最核心、最常用的工具结合实战场景深入讲讲怎么用以及背后的门道。4.1 电话呼叫工具让AI替你开口这是最核心的功能工具是make_call。基本用法 在AI对话中你可以直接说“用助手 [助手ID] 给电话号码 [8613812345678] 打个电话。” AI会理解并调用make_call(assistant_idasst_xxx, phone_number8613812345678)。参数详解与技巧assistant_id这是你在Famulor平台创建的AI助手的唯一标识。如何获取先使用get_assistants工具列出所有助手从返回的JSON中找到id字段。通常以asst_开头。phone_number必须使用E.164格式。即国家代码地区号手机号且不含空格、连字符等任何分隔符。例如中国北京的一个号码8613812345678。这是国际电信标准Famulor API严格要求此格式否则调用会失败。variables(可选)这是一个对象字典用于在通话中注入动态变量。例如如果你在助手的系统提示词中写了“客户的名字是 {{customer_name}}”那么你可以在调用时传入{customer_name: 张三}。这个功能非常强大可以实现批量个性化外呼。实战场景示例 假设你有一个用于“会议确认”的助手ID是asst_conf123。你想让它给李四打电话。 你可以对AI说“帮我用‘会议确认’助手给李四打个电话他的号码是8613912345678记得在通话里用上他的名字‘李四’和会议时间‘明天下午3点’。” AI可能会组合调用工具先获取助手列表找到对应ID然后执行{ assistant_id: asst_conf123, phone_number: 8613912345678, variables: { customer_name: 李四, meeting_time: 明天下午3点 } }注意事项通话成本通过API发起的通话通常是收费的费用取决于通话时长和目的地。在Famulor平台后台可以查看资费标准。合规性在用于真实客户外呼前务必了解并遵守你所在地区的电话营销法规如美国的TCPA中国的《通信短信息和语音呼叫服务管理规定》确保已获得客户同意。测试建议先用你自己的手机号或测试号码进行充分测试确保助手的对话流程、语音自然度都符合预期再用于正式场景。4.2 助手管理工具你的AI员工档案库get_assistants工具是你管理所有AI助手的中枢。它返回的是分页列表。高级查询技巧 虽然工具本身可能只支持分页参数page,per_page但你可以通过AI的上下文来筛选。例如你有几十个助手想找那个专门用于“售后回访”的。 你可以对AI说“帮我找出所有助手看看有没有名字里带‘回访’或者‘售后’的。” AI在拿到列表后会在其内部进行文本匹配和筛选然后呈现给你结果。结合update_assistant实现动态配置 这是进阶玩法。你可以让AI根据实时情况动态调整助手的配置。例如你发现某个助手的回复太机械想临时调高它的“创造力”对应LLM的temperature参数。 你可以对AI说“把助手‘销售顾问’的LLM温度参数调到0.8让它回答更灵活一些。” AI会调用update_assistant工具只更新llm_temperature字段为0.8而不会影响其他设置。4.3 线索与营销活动工具自动化营销引擎list_campaigns,create_lead,update_campaign_status这几个工具组合起来可以构建一个简单的自动化营销流水线。典型工作流创建活动在Famulor网页后台创建一个外呼活动Campaign设置好使用的助手、重试策略等。导入线索使用create_lead工具通过AI对话或结合其他自动化脚本将客户电话和变量批量添加到活动中。allow_duplicate参数可以控制是否允许同一号码重复添加。启动/监控活动用update_campaign_status工具通过AI指令“启动‘春季促销’活动”来触发批量外呼。同时可以随时用list_calls查看通话结果。更新线索状态当AI助手在通话中获取到新信息如“客户已购买”可以通过update_lead工具更新该线索的状态为“已完成”避免重复拨打。心法将Famulor视为执行层而你的AI对话界面ChatGPT/Claude作为指挥层。你用人话描述营销任务AI将其分解为对MCP工具的一系列精确调用。这极大地降低了自动化运营的认知负担和技术门槛。4.4 短信工具通话后的补充触达send_sms工具让你能在通话结束后自动或手动发送一条跟进短信。例如AI助手在电话里确认了订单挂断后立即发送一条包含订单详情的短信。关键点from参数需要的是你在Famulor平台拥有的、且支持短信功能的电话号码的ID而不是单纯的号码。你需要先用get_phone_numbers工具查看可用的号码及其ID。成本与长度短信按条计费长短信会被拆分通常超过160个英文字符或70个中文字符按多条计费。在发送前让AI帮你计算一下内容长度和预估成本是个好习惯。5. 高级技巧与故障排查实录用了一段时间后我积累了一些让体验更顺畅的技巧也遇到了不少坑。这里分享出来希望能帮你节省时间。5.1 配置优化与维护技巧环境变量管理API Key如果你觉得把API Key明文写在mcp.json里不安全虽然文件通常在本机或者需要在多台机器上同步配置但Key不同可以使用环境变量。在终端中设置环境变量# macOS/Linux export FAMULOR_API_KEYyour_key_here # Windows (PowerShell) $env:FAMULOR_API_KEYyour_key_here然后在mcp.json配置中删除env部分服务器会自动从进程环境变量中读取。{ mcpServers: { famulor: { command: node, args: [/path/to/dist/index.js] } } }注意这种方式要求你每次启动AI客户端时所在的终端环境都已经设置好了这个变量。对于桌面应用可能需要通过启动脚本或系统级环境变量来设置。项目级与全局配置像Cursor这样的工具支持项目级(.cursor/mcp.json)和全局级(~/.cursor/mcp.json)配置。最佳实践是在全局配置中放置像Famulor这样通用的、与具体项目无关的MCP服务器。只在项目级配置中放置与该项目强相关的工具如特定数据库的MCP服务器。JSON配置文件验证90%的“服务器未找到”错误源于mcp.json语法错误。一个多余的逗号、缺失的引号都会导致整个配置失效。在修改后使用在线的JSON验证工具如 JSONLint 粘贴校验一下能避免很多头疼的问题。5.2 常见问题与解决方案速查表下表是我和社区里遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案AI客户端完全找不到/不提及Famulor工具1. MCP配置未加载2. 配置文件路径错误3. JSON语法错误4. 客户端不支持该配置方式1.彻底重启AI客户端。2. 检查配置文件路径是否正确Claude在macOS是~/Library/Application Support/...。3. 校验mcp.json的JSON语法。4. 确认客户端支持Claude仅支持command模式Cursor/ChatGPT支持http(SSE)模式。连接失败 / 服务器错误1. 本地服务器未启动或构建失败2. API Key无效或过期3. 在线服务不可用4. Node.js版本过低1. 本地部署在项目目录运行node dist/index.js看是否有错误输出。2. 去Famulor后台验证API Key状态或新建一个。3. 访问https://mcp.famulor.io/health检查在线服务状态。4. 运行node --version确保版本≥20。工具调用返回“权限错误”或“未授权”1. API Key权限不足2. API Key未正确传递1. 检查该API Key在Famulor后台是否拥有调用相应工具如make_call的权限。2. 检查配置env字段名是否为FAMULOR_API_KEYCursor的Header格式是否正确Bearer空格Keymake_call失败提示号码格式错误电话号码格式不符合E.164标准确保号码格式为[国家代码][号码]例如8613812345678。移除所有空格、横线、括号。Claude能找到工具但调用时无反应或超时1. 本地服务器进程崩溃2. 网络问题导致连接Famulor API失败1. 查看系统控制台或终端是否有Node.js进程报错信息。2. 尝试在终端直接运行服务器并手动模拟一个简单请求看是否能连通Famulor API。检查网络代理设置。使用在线服务器但提示“Invalid API Key”API Key在HTTP Header中格式错误仅Cursor确认Cursor配置中headers.Authorization的值是Bearer your_keyBearer后有一个空格。5.3 调试与日志查看当问题比较复杂时查看日志是终极手段。本地服务器日志在运行npm run dev开发模式或直接运行node dist/index.js时所有与Famulor API的交互日志和错误都会打印到控制台。这是最详细的调试信息。AI客户端日志Claude Desktop日志位置因系统而异。macOS通常在~/Library/Logs/Claude/或通过Console.app查看。Cursor在设置中开启“Debug Mode”或查看开发者工具F12的控制台。ChatGPT Desktop日志路径类似~/Library/Application Support/ChatGPT/logs。网络抓包对于在线服务器模式可以使用像Charles或Fiddler这样的抓包工具查看客户端与mcp.famulor.io之间的SSE连接和事件流有助于理解通信过程。最后一个最朴素的建议从最简单的工具开始测试。不要一上来就尝试复杂的make_call。先试试get_assistants或list_calls这种只读、无副作用的工具。如果它们能正常工作说明基础连接和认证是通的再逐步测试更复杂的功能。这种渐进式验证能帮你快速定位问题所在的环节。