使用说明

Twilio MCP服务器

Twilio的模型上下文协议（MCP）服务器，支持AI驱动的SMS消息传递和智能对话管理。

特性

发送短信 -通过自动对话线程通过Twilio发送短信
接收短信 -通过带有自动存储功能的webhooks处理入站消息
会话管理 -跟踪和管理多回合短信对话
消息状态 -检查已发送邮件的传递状态
线程关联 -自动将消息链接到对话线程
彩信支持 -发送和接收彩信（可选）

安装

# Clone the repository
git clone <repository-url>
cd twilio-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

复制环境模板：

cp .env.example .env

在中填写您的Twilio凭据 .env:

# Get these from https://console.twilio.com
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

# Webhook configuration
WEBHOOK_PORT=3000
WEBHOOK_BASE_URL=https://your-domain.com

# Database path
DATABASE_PATH=./data/twilio.db

设置Webhooks

对于接收入站短信的服务器，您需要配置Twilio webhooks：

开发（使用ngrok）

安装ngrok：https://ngrok.com/download
启动webhook服务器：

npm run dev

在另一个终端中，启动ngrok：

ngrok http 3000

从ngrok复制HTTPS URL（例如。， https://abc123.ngrok.io)
配置Twilio webhook：
- 首选https://console.twilio.com/us1/develop/phone-numbers/manage/incoming
- 选择您的电话号码
- 在“消息配置”下：
  - Webhook URL: https://abc123.ngrok.io/webhooks/twilio/sms
  - HTTP方法：POST
- 在“状态回调URL”下：
  - 网址： https://abc123.ngrok.io/webhooks/twilio/status
- 保存

生产

使用HTTPS将webhook服务器部署到生产环境，并相应地配置Twilio webhook URL。

使用Claude代码

将此服务器添加到您的Claude Code MCP配置中：

{
  "mcpServers": {
    "twilio": {
      "command": "node",
      "args": ["/path/to/twilio-mcp/dist/index.js"],
      "env": {
        "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TWILIO_AUTH_TOKEN": "your_auth_token",
        "TWILIO_PHONE_NUMBER": "+1234567890",
        "WEBHOOK_PORT": "3000",
        "WEBHOOK_BASE_URL": "https://your-webhook-url.com",
        "DATABASE_PATH": "./data/twilio.db"
      }
    }
  }
}

MCP工具

send_sms

通过Twilio发送短信。

参数：

to （必填）：E.164格式的收件人电话号码（+1234567890）
message （必填）：短信内容（1-1600个字符）
from （可选）：发件人电话号码（如果未提供，则使用默认号码）
conversationId （可选）：现有对话的UUID

例子：

{
  "to": "+1234567890",
  "message": "Hello from Twilio MCP!"
}

答复：

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "to": "+1234567890",
  "from": "+1987654321",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

get_bound_消息

查询从存储中收到的短信/彩信。

参数：

from （可选）：按发件人电话号码筛选
to （可选）：按收件人电话号码筛选
conversationId （可选）：按对话UUID筛选
since （可选）：ISO 8601时间戳，用于过滤此日期之后的消息
limit （可选）：要返回的最大消息数（默认值：50）

例子：

{
  "from": "+1234567890",
  "limit": 10
}

create_conversation

初始化一个新的对话线程。

参数：

participants （必填）：E.164格式的电话号码数组（最少2个）
metadata （可选）：自定义元数据对象

例子：

{
  "participants": ["+1234567890", "+1987654321"],
  "metadata": {
    "campaign": "support",
    "priority": "high"
  }
}

get_对话_线程

检索所有消息的完整对话历史记录。

参数：

conversationId （必填）：对话的UUID
includeContext （可选）：包括AI上下文摘要（默认值：false）

例子：

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "includeContext": true
}

get_message状态

检查已发送邮件的传递状态。

参数：

messageSid （必填）：Twilio消息SID

例子：

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

答复：

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "delivered",
  "timestamp": "2025-01-15T10:31:00.000Z",
  "to": "+1234567890",
  "from": "+1987654321"
}

对话线程

服务器自动创建和管理对话线程：

出站消息：发送短信时：
- 如果 conversationId 如果提供了该消息，则该消息将链接到该对话
- 如果没有提供，服务器将按参与者对查找现有对话
- 如果不存在对话 AUTO_CREATE_CONVERSATIONS=true，创建了一个新的
入站邮件：通过webhook接收短信时：
- 服务器按参与者对（从/到数字）进行匹配
- 如果不存在对话 AUTO_CREATE_CONVERSATIONS=true，创建了一个新的
- 消息会自动存储并链接到对话
参与者匹配：对话由标准化的参与者对标识：
- [+1234567890, +1987654321] 无论方向如何，都能匹配相同的对话

建筑

twilio-mcp/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── server.ts                # MCP server with tool registry
│   ├── webhook-server.ts        # Express server for webhooks
│   ├── config/
│   │   └── env.ts               # Environment configuration
│   ├── services/
│   │   └── twilio-client.ts     # Twilio SDK wrapper
│   ├── storage/
│   │   ├── conversation-store.ts # Conversation persistence
│   │   └── message-store.ts      # Message persistence
│   ├── tools/
│   │   ├── send-sms.ts
│   │   ├── get-inbound-messages.ts
│   │   ├── create-conversation.ts
│   │   ├── get-conversation-thread.ts
│   │   └── get-message-status.ts
│   └── types/
│       └── models.ts            # TypeScript type definitions
└── data/                        # SQLite database storage

发展

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Type check
npm run lint

测试

该项目包括一个使用Jest和TypeScript支持的全面测试套件。

测试结构

tests/
├── setup.ts                    # Test environment setup
├── config/
│   └── env.test.ts             # Environment configuration validation tests
├── services/
│   └── twilio-client.test.ts   # Twilio client service tests
├── storage/
│   ├── conversation-store.test.ts  # Conversation persistence tests
│   └── message-store.test.ts       # Message persistence tests
├── tools/
│   ├── send-sms.test.ts            # SMS sending schema validation
│   ├── create-conversation.test.ts # Conversation creation tests
│   ├── get-conversation-thread.test.ts
│   ├── get-inbound-messages.test.ts
│   └── get-message-status.test.ts
└── webhook-server.test.ts      # Webhook endpoint tests

测试内容

架构验证：所有MCP工具输入模式都经过有效/无效输入测试
存储操作：SQLite对话和消息存储（CRUD操作）
Webhook处理程序：带有签名验证的入站短信和状态回调端点
环境配置：所有环境变量验证规则
Twilio客户端：客户端实例化和方法签名

运行测试

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

测试环境

测试使用内存中的SQLite数据库和在中配置的模拟环境变量 tests/setup.ts.

安全

没有硬编码的秘密：所有凭据都存储在环境变量中
Webhook验证：所有Twilio Webhook都使用签名验证进行验证
输入验证：所有工具输入都使用Zod模式进行验证
需要HTTPS：Webhook端点在生产环境中必须使用HTTPS

数据库

服务器使用SQLite存储对话和消息：

对话：线程元数据、参与者、时间戳
消息：短信/彩信内容、发送状态、媒体URL

数据库文件位置： ./data/twilio.db （可通过以下方式配置 DATABASE_PATH)

环境变量

变量	必填	默认	描述
`TWILIO_ACCOUNT_SID`	是	-	Twilio帐户SID（以AC开头）
`TWILIO_AUTH_TOKEN`	是	-	Twilio授权令牌
`TWILIO_PHONE_NUMBER`	是	-	您的Twilio电话号码（E.164格式）
`WEBHOOK_PORT`	没有	3000	webhook服务器端口
`WEBHOOK_BASE_URL`	是	-	webhooks的公共HTTPS URL
`DATABASE_PATH`	没有。/data/twilio.db	SQLite数据库文件路径
`LOG_LEVEL`	否	信息	日志记录级别（调试、信息、警告、错误）
`AUTO_CREATE_CONVERSATIONS`	否	true	自动为新线程创建对话
`ENABLE_AI_CONTEXT`	否	true	启用AI上下文生成
`ENABLE_MMS`	否	真	启用彩信支持

许可证

麻省理工学院

支持

对于问题和疑问：

Twilio文档：https://www.twilio.com/docs
MCP文件：https://modelcontextprotocol.io

使用说明

Twilio MCP服务器

特性

安装

配置

设置Webhooks

开发（使用ngrok）

生产

使用Claude代码

MCP工具

send_sms

get_bound_消息

create_conversation

get_对话_线程

get_message状态

对话线程

建筑

发展

测试

测试结构

测试内容

运行测试

测试环境

安全

数据库

环境变量

许可证

支持

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

ChatGPT交互工具