Twilio SMS MCP Server

Twilio短信MCP服务器

生产级 模型上下文协议 Twilio短信服务器。\ 通过任何兼容MCP的客户端（VS Code Copilot、Codex CLI、Claude Desktop等）发送、接收、安排、编辑和检查SMS/MMS对话。

______________________________________________________________________

特性

工具（16）

资源

提示

生产硬化

• 使用指数回退重试 关于瞬态Twilio API错误（429，5xx，网络故障）
• Webhook速率限制 --每个IP节流阀的内存中（120个请求/分钟）
• 结构化日志记录 --stderr上有时间戳、水平、一致的格式
• 输入验证 --Pydantic v2严格模式，E.164，SID模式强制
• Webhook签名验证 --提里奥 RequestValidator 在所有入站挂钩上
• 健康和准备终点 — /healthz, /readyz 对于管弦乐队
• Docker多阶段构建 使用非root用户、健康检查、持久卷
• py.typed 下游类型检查器兼容性标记

需求

• Python 3.11+
• Twilio帐户和Twilio电话号码
• 对于定时消息：Twilio消息服务SID
• 对于入站消息：一个可公开访问的webhook URL
• Docker桌面（可选，用于容器部署）

快速开始

cp env.example .env          # fill in your Twilio credentials; for local runs set TWILIO_DB_PATH=inbox.db
pip install -e ".[dev]"
pytest                        # run the test suite
python -m twilio_sms_mcp.boot # start MCP + webhook server

客户端配置

VS代码（GitHub复制/复制聊天）

添加到您的VS代码 settings.json 或 .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "twilio-sms": {
        "command": "python",
        "args": ["-m", "twilio_sms_mcp.boot"],
        "env": {
          "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "TWILIO_AUTH_TOKEN": "your_auth_token_here",
          "TWILIO_FROM_NUMBER": "+12025551234"
        }
      }
    }
  }
}

克劳德桌面版

添加 claude_desktop_config.json （macOS： ~/Library/Application Support/Claude/，Windows： %APPDATA%\Claude\):

{
  "mcpServers": {
    "twilio-sms": {
      "command": "python",
      "args": ["-m", "twilio_sms_mcp.boot"],
      "env": {
        "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TWILIO_AUTH_TOKEN": "your_auth_token_here",
        "TWILIO_FROM_NUMBER": "+12025551234"
      }
    }
  }
}

Codex 命令行界面

codex mcp add twilio-sms \
  -- docker run --rm -i \
  --env-file .env \
  -p 8080:8080 \
  -v twilio_sms_data:/data \
  twilio-sms-mcp

验证：

codex mcp get twilio-sms
codex mcp list

码头工人

构建并运行：

docker build -t twilio-sms-mcp .
docker run --rm -i \
  --env-file .env \
  -p 8080:8080 \
  -v twilio_sms_data:/data \
  twilio-sms-mcp

或者使用Docker Compose：

docker compose up -d

Webhook注释

• 将Twilio配置为POST /webhook/sms 对于入站消息。
• 将Twilio配置为POST /webhook/status 用于交付回访。
• 集 TWILIO_PUBLIC_WEBHOOK_BASE_URL 当在反向代理或ngrok后面时。
• 保持 TWILIO_VALIDATE_WEBHOOK_SIGNATURES=true 在生产中。

环境变量

测试

pip install -e ".[dev]"
pytest -v

生产清单

• \[\]使用HTTPS进行webhook传递
• \[\]设置 TWILIO_VALIDATE_WEBHOOK_SIGNATURES=true
• \[\]对发件人池和计划邮件使用消息服务SID
• \[\]坚持 /data 卷，使收件箱状态在重新启动后仍然存在
• \[\]永不承诺 .env --它被排除在外 .gitignore 和 .dockerignore
• \[\]监视器 /healthz 和 /readyz 来自您的编排器
• \[\]设置 TWILIO_LOG_LEVEL=WARNING 在高流量环境中

许可证

麻省理工学院