Klavis 仓库 Twilio MCP Server 实战指南15 个原子工具实现 SMS、语音、号码管理与账户监控【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇技术指南以 Klavis 开源仓库中 mcp_servers/twilio/README.md 为骨架结合 server.py 及 tools/ 下的完整源码实现系统讲解该 Twilio MCP Server 的架构设计、15 个原子工具的参数细节、双模式运行方式stdio / HTTP与 Docker 部署流程。读完本文你将掌握如何把 Twilio 的短信、语音、号码管理与账户监控能力接入 Claude Desktop 或其他 MCP 客户端让 AI Agent 能够直接发送消息、拨打电话、采购号码并核对账户余额。一、项目概述为 AI Agent 提供可靠的 Twilio 通信能力Twilio MCP Server 是基于 Model Context ProtocolMCP规范的完整服务端实现通过一组原子化atomic、设计良好的工具为 AI Agent 提供与 Twilio 通信 API 的全面集成。它覆盖了 Twilio 的四大能力域SMS 与 MMS 消息发送文本与多媒体消息支持投递状态追踪语音呼叫通过 TwiML 指令发起与管控电话呼叫号码管理搜索、购买、配置与释放电话号码账户监控查询余额、用量记录与账户信息。其核心特性包括 15 个覆盖 Twilio 通信 API 的工具、stdio 与 HTTP 双模式架构、基于 context 的令牌管理、可配置日志以及带可操作性错误信息的全面异常处理。二、工具全景四大类别 15 个原子工具服务端将 15 个工具按业务域划分为四个类别。以下参数表直接来源于 server.py 中get_all_tools()声明的inputSchema每个工具都带有明确的category注解TWILIO_MESSAGING、TWILIO_VOICE、TWILIO_PHONE、TWILIO_ACCOUNT、TWILIO_USAGE供客户端做能力分类与权限管理。2.1 消息类Messaging Operations工具名功能必填参数关键可选参数twilio_send_sms发送 SMS支持投递追踪to、from_、bodystatus_callback投递状态回调 URLtwilio_send_mms发送多媒体消息最多 10 个附件to、from_body、media_url附件 URL 数组、status_callbacktwilio_get_messages查询消息历史支持灵活过滤无limit默认 20最大 1000、date_sent_after、date_sent_before、from_、totwilio_get_message_by_sid按 SID 获取单条消息详情message_sid—参数细节以源码 Schema 为准twilio_send_sms.body消息内容上限 1600 字符源码在 messaging.py 中显式校验超出直接抛出ValueErrortwilio_send_mms.media_url媒体 URL 列表源码在 messaging.py 中限制最多 10 个附件且要求body与media_url至少提供一个twilio_get_messages返回结构包含messages列表、count以及filters_applied回显本次实际生效的过滤条件每条消息含sid、status、direction、price、price_unit、date_sent等字段。2.2 语音类Voice Operations工具名功能必填参数关键可选参数twilio_make_call发起电话呼叫通过 TwiML 控制通话流程to、from_urlTwiML URL或twimlTwiML 字符串、method默认 POST、status_callback、timeout默认 60 秒、record默认 falsetwilio_get_calls查询通话历史支持状态过滤无limit、status、from_、to、start_time_after、start_time_beforetwilio_get_call_by_sid按 SID 获取通话详情时长、费用等call_sid—twilio_get_recordings获取通话录音用于质检、合规或分析无limit、call_sid、date_created_after、date_created_before调用语义源码约束见 voice.pytwilio_make_call的url与twiml二者必须提供其一且不能同时提供否则抛出ValueErrortwilio_get_calls.status枚举值固定为queued、ringing、in-progress、completed、busy、failed、no-answer、canceled非法值会被源码拒绝voice.pytwilio_get_call_by_sid额外返回forwarded_from、caller_name、parent_call_sid、answered_by、start_time、end_time等深度信息。2.3 号码管理类Phone Number Management工具名功能必填参数关键可选参数twilio_search_available_numbers按区号或数字模式搜索可购买号码无country_code默认US、area_code、contains、sms_enabled默认 true、voice_enabled默认 true、limit默认 20最大 50twilio_purchase_phone_number购买号码并可配置 Webhookphone_numberfriendly_name、voice_url、sms_url、status_callbacktwilio_list_phone_numbers查看名下全部号码及其配置无limit默认 20最大 1000twilio_update_phone_number修改号码配置与 Webhookphone_number_sidfriendly_name、voice_url、sms_url、status_callbacktwilio_release_phone_number释放号码、停止计费不可撤销phone_number_sid—实现细节见 phone_numbers.pytwilio_search_available_numbers底层根据国家代码调用client.available_phone_numbers(country).local.list(...)返回结果包含号码的capabilitiesvoice / sms / mms / fax能力矩阵twilio_update_phone_number要求至少提供一个待更新字段否则报错phone_numbers.pytwilio_release_phone_number是危险操作源码会先fetch()号码详情用于回显再执行delete()返回success: true与释放的号码明文提示该操作无法撤销。2.4 账户与用量监控类Account Usage Monitoring工具名功能必填参数关键可选参数twilio_get_account_info获取账户详情与状态无—twilio_get_balance查询当前账户余额无—twilio_get_usage_records按类别与时间段生成用量报告无category、start_date、end_date、granularitydaily/monthly/yearly/all-time默认daily、limit默认 50最大 1000实现亮点见 account.pytwilio_get_balance调用client.balance.fetch()返回account_sid、balance、currencytwilio_get_usage_records依据granularity动态映射到 Twilio SDK 的不同端点daily→usage.records.daily、monthly→usage.records.monthly、yearly→usage.records.yearly、all-time→usage.recordsaccount.py并在返回的summary中自动累加total_usage与total_price便于直接做账单分析。三、架构剖析双模式服务端与统一工具路由从源码看服务端采用一份工具定义 统一路由 双传输层的架构有效避免了 stdio 与 HTTP 两种模式下的代码重复。3.1 入口与命令行参数server.py 使用click定义入口支持四个 CLI 选项选项默认值说明--port环境变量TWILIO_MCP_SERVER_PORT默认5000HTTP 模式监听端口--log-levelINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICAL--json-responsefalse启用后 StreamableHTTP 返回 JSON 响应而非 SSE 流--stdiofalse以 stdio 模式运行供 Claude Desktop 等客户端使用不加该参数则默认进入 HTTP 模式3.2 统一工具路由call_tool_routerget_all_tools()集中声明全部 15 个工具的types.Tool定义call_tool_router(name, arguments)server.py则统一完成工具调用分发。关键逻辑每次调用前从环境变量读取TWILIO_AUTH_TOKEN并写入auth_token_context保证令牌随请求上下文流转通过 if/elif 链把工具名映射到 tools/ 包中对应的异步实现函数未知工具名抛出ValueError(fUnknown tool: {name})。stdio 与 HTTP 两种模式下的list_tools/call_tool回调都复用上述两个函数这正是dual mode架构能保持行为一致的原因。3.3 认证机制ContextVar 令牌上下文tools/base.py 定义了一个ContextVar类型的auth_token_context实现上下文感知的令牌管理HTTP 模式下服务端会从请求头x-auth-token提取令牌server.py 的 SSE 处理与 server.py 的 StreamableHTTP 处理均如此提取不到时回退到环境变量get_auth_token()优先从 ContextVar 读取为空或未设置时回退TWILIO_AUTH_TOKEN两者都缺失则抛出RuntimeError请求结束时在finally中执行auth_token_context.reset(token)防止令牌跨请求泄漏。同时 base.py 提供了统一的validate_phone_number()号码规范化函数去除空格、横杠、括号自动补齐前缀11 位以1开头或 10 位号码分别规范化为1...格式从源头保证所有工具收到的号码符合 E.164 格式。3.4 双传输层HTTP 模式HTTP 模式server.py基于 Starlette uvicorn 构建 ASGI 应用同时挂载了两条传输通道端点方法传输协议用途/GET—健康检查/sseGETSSE配合/messages/端点回传传统 SSE 流式 MCP 传输/mcpPOSTStreamableHTTP新版 Streamable HTTP 传输--json-response开关决定返回 JSON 还是 SSE 流会话管理通过StreamableHTTPSessionManager实现当前配置为statelessTrue的无状态模式源码注释指出可通过接入 event store 改为有状态。四、安装与配置4.1 前置条件Twilio 账户前往 twilio.com 注册API 凭证在 Twilio Console 获取 Account SID 与 Auth TokenPython 3.8运行服务端所需电话号码至少购买一个 Twilio 号码用于发消息/打电话。4.2 获取 Twilio 凭证登录 Twilio Console进入Account Dashboard复制Account SID与Auth Token可选在Phone Numbers Manage Buy a number购买号码。4.3 安装依赖# 进入 Twilio MCP server 目录 cd mcp_servers/twilio # 创建虚拟环境推荐 python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate # 安装依赖 pip install -r requirements.txtrequirements.txt 中的核心依赖如下其中twilio9.0.0提供 REST API 客户端mcp1.11.0提供 MCP 协议实现starletteuvicorn支撑 HTTP/SSE 传输python-dotenv负责加载.envmcp1.11.0 click8.0.0 python-dotenv0.19.0 starlette0.49.1 twilio9.0.0 pydantic2.0.0 uvicorn0.30.04.4 配置环境变量README 中给出的配置流程是复制.env.example为.env若仓库目录中未附带该示例文件也可直接手动创建.env并写入以下变量# 复制示例环境文件 cp .env.example .env # 编辑 .env nano .env # 或 vim .env / code .env填入凭证与端口TWILIO_ACCOUNT_SIDyour_account_sid_here TWILIO_AUTH_TOKENyour_auth_token_here TWILIO_MCP_SERVER_PORT5000三个变量的作用TWILIO_ACCOUNT_SID账户标识get_account_sid()只从环境变量读取缺失即抛错base.pyTWILIO_AUTH_TOKEN认证令牌既是 stdio/环境回退来源也是 HTTP 模式x-auth-token请求头的兜底TWILIO_MCP_SERVER_PORTHTTP 模式默认端口作为--port的默认值。五、运行服务端stdio 与 HTTP 双模式5.1 模式一Claude Desktop 集成stdiopython server.py --stdio在claude_desktop_config.json中注册{ mcpServers: { twilio: { command: /path/to/your/venv/bin/python, args: [/path/to/mcp_servers/twilio/server.py, --stdio], env: { TWILIO_ACCOUNT_SID: your_account_sid_here, TWILIO_AUTH_TOKEN: your_auth_token_here } } } }stdio 模式server.py通过标准输入/输出与 MCP 客户端通信调试信息以[TWILIO-DEBUG]前缀写入 stderr避免污染 stdout 协议流工具返回结果统一以json.dumps(result, indent2)序列化为TextContent。5.2 模式二HTTP 服务器默认python server.py # 服务运行于 http://localhost:5000自定义配置选项# 自定义端口与日志级别 python server.py --port 8080 --log-level DEBUG # 启用 JSON 响应替代 SSE 流 python server.py --json-response5.3 Docker 部署Dockerfile 基于python:3.11-slim构建包含非 root 用户app、30 秒间隔的HEALTHCHECK请求/端点以及默认端口 5000 的暴露配置。# 1. 配置环境变量见上文 cp .env.example .env # 编辑 .env 填入 Twilio 凭证 # 2. 构建镜像 docker build -t twilio-mcp-server . # 3. HTTP 模式运行默认 docker run -p 5000:5000 --env-file .env twilio-mcp-server # 4. stdio 模式运行供 MCP 客户端集成 docker run --env-file .env twilio-mcp-server --stdio六、验证部署健康检查与工具调用6.1 快速测试命令服务运行于 localhost:5000 时# 健康检查 curl http://localhost:5000/ # 列出可用工具 curl -X POST http://localhost:5000/ \ -H Content-Type: application/json \ -d {method: tools/list} # 测试账户信息工具需要 .env 中已有凭证 curl -X POST http://localhost:5000/ \ -H Content-Type: application/json \ -d {method: tools/call, params: {name: twilio_get_account_info, arguments: {}}}6.2 测试 Claude Desktop 集成将服务端加入 Claude Desktop 配置并重启直接向 Claude 提问Can you check my Twilio account balance?Claude 会调用twilio_get_balance工具返回余额。七、典型工具调用示例以下 JSON 载荷可直接用于tools/call请求或作为 AI Agent 的工具调用参数模板。7.1 发送 SMS{ tool: twilio_send_sms, arguments: { to: 1234567890, from_: 1987654321, body: Hello from Twilio MCP Server! } }7.2 发起语音呼叫{ tool: twilio_make_call, arguments: { to: 1234567890, from_: 1987654321, twiml: ResponseSayHello, this is a test call from Twilio!/Say/Response } }7.3 搜索可购买号码{ tool: twilio_search_available_numbers, arguments: { country_code: US, area_code: 415, sms_enabled: true, voice_enabled: true, limit: 10 } }7.4 生成用量报告{ tool: twilio_get_usage_records, arguments: { category: sms, granularity: daily, start_date: 2024-01-01, end_date: 2024-01-31 } }八、错误处理与故障排查服务端为每个工具都实现了 try/except 包装错误信息会连同工具名与参数一并回传stdio 模式下返回{error: ..., tool: ..., arguments: ...}结构HTTP 模式下返回Error: 消息文本便于客户端直接定位问题。8.1 常见错误场景认证错误核对TWILIO_ACCOUNT_SID与TWILIO_AUTH_TOKEN是否正确确认凭证未被轮换或过期号码格式错误号码必须符合 E.164 格式如1234567890美国号码含国家码共 11 位——工具内部会先经validate_phone_number()规范化无法规范化即抛ValueError权限错误确认 Twilio 账户权限充足且所在区域已开通 SMS / Voice 服务限流Twilio 对 API 调用与消息发送有速率限制生产环境应实现指数退避exponential backoff重试策略。8.2 调试技巧# 开启 DEBUG 日志 python server.py --log-level DEBUG日志格式为%(asctime)s - %(name)s - %(levelname)s - %(message)s每个工具调用、成功与失败都会输出带上下文的日志如 Sending SMS from ... to ...、SMS sent successfully. SID: ...可用 Twilio Console 的 REST API Explorer 先行验证凭证再通过 Console 发送测试消息HTTP 模式可在请求头附加x-auth-token覆盖环境变量令牌便于多租户场景测试。九、开发与测试建议搭建开发环境复用前述虚拟环境与依赖安装流程使用 Twilio 测试凭证Twilio 提供的测试凭证不会发送真实消息或拨打真实电话适合在开发阶段反复验证工具链路覆盖测试参照仓库 Contributing Guide 的要求对所有工具同时用合法与非法输入测试确保 Twilio API 错误的处理路径完善新增工具时补充使用示例与文档。十、进一步探索阅读 mcp_servers/twilio/README.md 获取原始文档深入 server.py 了解双模式入口、CLI 参数与双传输层实现研读 tools/base.py 掌握 ContextVar 令牌上下文与 E.164 号码校验逻辑对照 tools/messaging.py、tools/voice.py、tools/phone_numbers.py、tools/account.py 查看每个工具的底层 SDK 调用链参考 Dockerfile 与 requirements.txt 复现容器化部署环境。本项目遵循 Apache 2.0 协议详见 LICENSE。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考