pbx-mcp 是一个 MCP（Model Context Protocol）服务器，用于让 AI 助手检查和控制 Asterisk 与 FreeSWITCH 电话系统。它解决的问题是：调试 PBX 通常需要记住两套完全不同的命令集——Asterisk 使用 AMI 和带有数百个动词的 CLI，FreeSWITCH 使用 ESL 及其自己的词汇体系；同时运行两者时，运维人员需要不断切换上下文。pbx-mcp 在两者之上提供一个统一、描述清晰的工具界面，使助手能从“呼叫失败”直接查到 sofia status gateway，而不需要人工逐步说明。
【主要能力】 服务器向 AI 助手暴露十二个只读工具，每个引擎六个，每个工具的描述都足够清晰，模型无需额外提示即可选择正确的工具。四个写入工具（asterisk_originate、asterisk_hangup、freeswitch_originate、freeswitch_hangup）在未设置 PBX_MCP_ALLOW_WRITE=true 之前保持隐藏，不会出现在工具列表中。
【使用方式】 运行需要 Node 18 或更高版本，多数 MCP 客户端配置直接使用 npx 运行。也可使用预构建的 Docker 镜像（Docker Hub 上的 ictinnovations/pbx-mcp）。使用 Docker 时有三个要点：-i 不是可选项，服务器通过 stdio 通信，若不连接 stdin 容器会启动后无输出，看起来像服务器损坏；没有需要发布的端口；PBX 必须能从容器内访问，若 Asterisk 运行在 Docker 宿主机上，Mac 和 Windows 下换成 host.docker.internal，Linux 下添加 --network host。镜像以非 root 用户运行，且与其他运行方式一样默认只读。
配置全部通过环境变量完成。可设置 Asterisk 块、FreeSWITCH 块或两者。服务器只为实际配置的引擎注册工具，因此仅使用 Asterisk 的环境不会看到 FreeSWITCH 工具。AMI 用户至少需要 read = system,call,command 和 write = command；若计划开启写入模式再添加 originate。
在 claude_desktop_config.json 中添加配置即可使用，任何支持 stdio 的 MCP 客户端同理。运行容器而非 npx 时保留 env 块并将 command 指向 Docker；每个不带值的 -e NAME 会把该变量从环境转发进容器，避免密钥出现在参数列表中。
【安全设计】 默认只读，并有多层防护。asterisk_cli 只接受检查类前缀的白名单（如 core show、pjsip show、dialplan show、queue show 等），freeswitch_api 接受同类列表（如 status、show、sofia status、db list 等），按命令起始匹配。FreeSWITCH 白名单是允许子命令而非拒绝危险词，例如 sofia status 属于读取，而 sofia profile internal restart 不在列表内会被拒绝。只读模式下写入工具完全不注册。挂断预览工具始终可用，可显示挂断会影响哪些活动通道而不实际执行。两个传输通道都会在发送前拒绝 shell 元字符，AMI 头部注入被阻止，输出被限制在 20000 字符以内。即使有这些防护，也建议给 AMI 用户最小权限，并把 PBX 置于防火墙之后而非公网。
【供给功能（仅 Asterisk，可选）】 另有六个工具通过 AMI UpdateConfig 创建、列出和删除 PJSIP 中继和 SIP 分机，仅在 PBX_MCP_ALLOW_PROVISION=true 时注册，与写入模式相互独立。编解码器支持 ulaw、alaw、g722、g729、opus；名称和号码匹配 ^[A-Za-z0-9_-]{1,32}$。使用时需在 pjsip.conf 旁创建受管文件并引入，给 AMI 用户额外权限（config、command，写入模式才需 originate）。所有供给调用在进程内串行化，因为 UpdateConfig 是读-改-写，每个受管文件只能运行一个供给器。分机注册名为 mcp-<number>，密码为 24 位随机 URL 安全字符，仅在创建响应中显示一次。
【使用限制】 项目在 Asterisk 22（认证 22.8）上测试。所用 PJSIP 选项和 UpdateConfig 特性在其他版本上需重新验证；TCP 和 TLS 中继虽可生成但未在真实对端上验证。由于 SIP 中继和可注册分机可能被用于长途欺诈，应把 PBX_MCP_CONTEXT_ALLOW 指向无法拨出 PSTN 的上下文，保持 PBX_MCP_TRUNK_ALLOW 尽量窄（主机名按字面比较、不解析，不支持 IPv6），空允许列表会拒绝一切。建议在实验室或测试 PBX 上试用，不要将 SIP 5060 或 AMI 5038 暴露到公网。
【底层客户端】 若不使用 MCP 而只想从 Node 代码与 PBX 通信，两个底层协议客户端已单独发布：asterisk-ami-node（npm install asterisk-ami-node）和 freeswitch-esl-node（npm install freeswitch-esl-node）。两者零依赖、TypeScript、同时支持 ESM 和 CommonJS、需 Node 18 以上，并针对模拟交换机测试过。
项目由 ICT Innovations 的 Tahir Almas 开发维护，采用 MIT 许可。
