voicent-mcp

Voicent MCP 服务

让 AI Agent 使用本地部署的 Voicent Gateway：拨打电话和发送短信、运行营销活动、查看结果，以及读取和更新 CRM 记录。

这是第一阶段，涵盖 Simple Gateway API、Campaign API 和 CRM API。任何需要更改产品的功能（例如 CRM 搜索）都将在第二阶段推出。

需要 Voicent Gateway 10.10.3 或更高版本。 在较旧版本中，音频电话会失败，保存请求时中文文本会丢失，客户字段中的撇号也会被错误保存。

Voicent 许可证： 你需要 Workflow 许可证和产品的 Enterprise Edition。

工具

单次电话、短信和 CRM 工具默认启用，营销活动工具默认关闭。关闭的工具对 Agent 不可用。

设置	工具
始终启用	call_status、campaign_status、import_status
除非 VOICENT_ALLOW_CALLS=0，否则启用	call_text、call_audio、call_ivr、send_sms、call_remove
除非 VOICENT_ALLOW_CRM=0，否则启用	crm_get_field、crm_add_or_update、crm_set_field、crm_add_note、crm_schedule_callback、crm_notify_agent
除非 VOICENT_ALLOW_CAMPAIGNS=1，否则关闭	campaign_import_list、campaign_upload_audio、campaign_export、campaign_run_autodialer、campaign_run_text、campaign_run_email

目前尚未包含：预测式拨号营销活动、定时或周期性营销活动、向远程 Gateway 上传文件，以及搜索、列出或删除 CRM 记录。由于不支持搜索，Agent 需要记录的 ID，或客户的电话号码或电子邮件地址。

设置

变量	用途
VOICENT_GATEWAY_URL	Gateway 地址。默认值：http://localhost:8155
VOICENT_ALLOW_CALLS	0 会关闭单次电话和短信。默认：启用
VOICENT_ALLOWED_NUMBERS	将单次电话和短信限制为这些以逗号分隔的号码。默认：任意号码
VOICENT_ALLOW_CRM	0 会关闭 CRM 工具。默认：启用
VOICENT_ALLOW_CAMPAIGNS	1 会启用营销活动和列表导入
VOICENT_FILE_ROOT	音频、导入和导出文件必须位于此文件夹内。未设置时，文件工具会拒绝运行
VOICENT_PASSWORD	Gateway 的 Remote Connect Password；当 Gateway 不在此计算机上时需要
VOICENT_USERNAME	登录名；当 VOICENT_PASSWORD 是用户密码而非 Remote Connect Password 时需要。在云服务模式下，账户所有者使用 admin，而不是电子邮件地址
VOICENT_ACCOUNT_ID	账户 ID（cc_card_id），仅云服务模式下的 Gateway 需要
VOICENT_TIMEOUT_MS	请求超时时间。默认值：30000

文件路径由 Gateway 读取，因此只有当此服务运行在 Gateway 所在计算机上时，文件工具才能正常工作。

安全

• 默认情况下，Agent 可以呼叫或发送短信给任意号码。 如需限制号码，例如在测试期间，请设置 VOICENT_ALLOWED_NUMBERS。如需关闭呼叫和短信功能，请设置 VOICENT_ALLOW_CALLS=0。
• VOICENT_ALLOWED_NUMBERS 不适用于营销活动。 营销活动会联系名单上的所有人，因此只有在可以接受的情况下才启用 VOICENT_ALLOW_CAMPAIGNS。
• 名单导入不像 CRM 工具那样受限。 campaign_import_list 可以通过 VOICENT_FILE_ROOT 中的文件更新匹配联系人任意列的值，包括清除 DO_NOT_CALL。这里只放入你自己也会导入的文件。
• CRM 读取会将客户记录发送给你的 AI 提供商，CRM 写入则会修改这些记录。 如需关闭 CRM 工具，请设置 VOICENT_ALLOW_CRM=0。
• CRM 工具限制： 只能读取或修改已知字段。Agent 可以将 DO_NOT_CALL 和 DO_NOT_EMAIL 设为 yes，但只有人工才能清除它们。除非 overwrite 为 true，否则 crm_add_or_update 只会填充空值。通知为纯文本。
• 保护网关本身。 这些限制仅适用于此服务。网关可从 localhost 访问，从其他位置访问则需要 Remote Connect Password。**请在 Voicent App > Setup > Options > Control 中设置你自己的密码，**因为远程登录可以部署 IVR 应用并运行 SQL。不要将端口暴露给不受信任的网络。某些呼叫流程页面没有密码检查。
• 请求由一组固定字段构建。服务绝不会发送 sql 或数据库字段、startvxml 或 starturl，也不会发送 ignorednc（此字段会绕过请勿呼叫限制）。
• 电话号码必须是严格格式的单个号码，以此阻止网关的特殊值 dbquery、dialer 和 vcenter。

运行

需要 Deno。

deno task test      # tests against a fake gateway; nothing is dialed
deno task start     # run from source
deno task compile   # build dist/voicent-mcp.exe, which runs without Deno

连接到 Claude Code

将以下内容添加到 .mcp.json：

{
  "mcpServers": {
    "voicent": {
      "command": "C:\\voicent-mcp\\voicent-mcp.exe",
      "env": {
        "VOICENT_GATEWAY_URL": "http://localhost:8155"
      }
    }
  }
}

连接之前： 使用此配置时，Agent 可以呼叫或发送短信给任意号码、读取 CRM 记录（这些记录会发送给你的 AI 提供商）并修改记录。将设置添加到 env 以更改此行为：

用途	添加
将呼叫和短信限制为特定号码	"VOICENT_ALLOWED_NUMBERS": "650-555-0100,650-555-0101"
关闭呼叫和短信功能	"VOICENT_ALLOW_CALLS": "0"
关闭 CRM 工具	"VOICENT_ALLOW_CRM": "0"
启用营销活动	"VOICENT_ALLOW_CAMPAIGNS": "1"
允许使用音频、导入和导出文件	"VOICENT_FILE_ROOT": "C:\\voicent-files"

每次启动时，服务都会在日志中重复显示这些警告。

与开发者文档的差异

服务发送的是网关实际读取的内容，以下方面与开发者文档有所不同：

• 电子邮件营销活动将内嵌内容作为 msginfo（主题）和 msgbody 传递，不带 msgtype。文档中描述的 msgtype=file 和 msgfilepath 并不会被网关读取。
• call_ivr 使用 startapp 字段。
• 每个请求都会将密码作为 agent_password 发送；用户登录时还会发送 agent_username。文档使用 passwd 表示 Remote Connect Password，网关也接受此字段名。

已知问题

• 电话和电子邮件查询在存在重复记录时可能匹配到错误的记录。 如果有记录 ID，请使用它。

• call_ivr 无法检查应用是否为外呼应用。 它会拒绝未部署的应用名称。请仅使用外呼应用。

• 没有应答机留言的 IVR 应用在接通语音信箱时，偶尔会以 failed 结束。请在 IVR Studio 中为应用添加留言。

许可证

此服务采用 MIT License；详见 LICENSE。它所连接的 Voicent 软件采用单独的许可证。