Twilio短信服务器
一个多功能的SMS服务，既可以作为Claude Desktop的模型上下文协议（MCP）服务器运行，也可以作为云部署的独立REST API运行。
🚀 两种部署模式
1.MCP服务器模式（本地与克劳德桌面）
使Claude和其他AI助手能够通过模型上下文协议发送短信。
2.Web API模式（云部署）
独立的REST API，可以部署到任何用于web应用程序的云平台。
✨ 特性
- 📱 通过Twilio发送短信
- 🌐 用于web集成的REST API端点
- 🔨 用于Claude Desktop集成的MCP服务器
- 📝 常见消息传递场景的预构建提示
- 🔒 Twilio凭据的安全处理
- 🐳 Docker支持，易于部署
- ☁️ 云部署就绪
📋 需求
- Node.js>=18
- 具有短信功能的Twilio帐户
- Twilio凭据的环境变量
⚙️ 环境设置
创建一个 .env 项目根目录中的文件：
# Twilio Configuration (Required)
ACCOUNT_SID=your_twilio_account_sid_here
AUTH_TOKEN=your_twilio_auth_token_here
FROM_NUMBER=+1234567890
# Server Configuration (Optional, defaults to 3000)
PORT=3000🚀 安装与使用
地方发展
# 安装依赖项
npm安装
# 构建项目
npm运行构建
# 作为MCP服务器运行（适用于Claude Desktop）
npm运行启动：mcp
# 作为Web API服务器运行
npm运行启动：web
# 开发模式（重建并启动web服务器）
npm运行dev:web
\`\`\`
## 🌐 Web API终结点
在Web API模式下运行时，以下端点可用：
### `GET /`
API文档和使用示例
### `GET /health`
健康检查端点
### `POST /send-sms`
发送短信
**请求正文：**
{ "to": "+11234567890", "message": "Your message here" }
**答复：**
{ "success": true, "message": "Message sent successfully", "messageSid": "SM...", "to": "+11234567890", "from": "+1234567890" }
### `POST /send-greeting`
在特殊场合发送问候信息
**请求正文：**
{ "to": "+11234567890", "occasion": "birthday", "customMessage": "Optional custom message" }
## 🖥️ 克劳德桌面配置（MCP模式）
要将此服务器与Claude Desktop一起使用，请将以下内容添加到配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
{ "mcpServers": { "twilio": { "command": "npx", "args": [ "-y", "@yiyang.1i/sms-mcp-server" ], "env": { "ACCOUNT_SID": "your_account_sid", "AUTH_TOKEN": "your_auth_token", "FROM_NUMBER": "your_twilio_number" } } } }
更新配置后，重新启动Claude Desktop。如果连接成功，您应该在下面看到Twilio🔨 菜单。
## ☁️ 云部署
### 方案1：铁路
1. 将您的GitHub存储库连接到 [铁路](https://railway.app)
1. 在铁路仪表板中设置环境变量
1. 自动部署
### 选项2：渲染
1. 将您的仓库连接到 [渲染](https://render.com)
1. 创建新的Web服务
1. 构建命令： `npm install && npm run build`
1. 启动命令： `npm run start:web`
1. 添加环境变量
### 选项3:Heroku
heroku create your-app-name heroku config:set ACCOUNT_SID=your_sid heroku config:set AUTH_TOKEN=your_token heroku config:set FROM_NUMBER=your_number git push heroku main
### 选项4:Docker
Build Docker image
docker build -t twilio-sms-server .
Run container
docker run -p 3000:3000 \ -e ACCOUNT_SID=your_sid \ -e AUTH_TOKEN=your_token \ -e FROM_NUMBER=your_number \ twilio-sms-server
## 🧪 测试API
### 局部测试
Start the server
npm run start:web
Test health endpoint
curl http://localhost:3000/health
Send a test SMS
curl -X POST http://localhost:3000/send-sms \ -H "Content-Type: application/json" \ -d '{"to": "+1234567890", "message": "Hello from the API!"}'
Send a greeting
curl -X POST http://localhost:3000/send-greeting \ -H "Content-Type: application/json" \ -d '{"to": "+1234567890", "occasion": "birthday"}'
## 💬 与Claude的交互示例（MCP模式）
以下是通过Claude与服务器交互的一些自然方式：
1. **简单短信：**
Send a text message to +11234567890 saying "Don't forget about dinner tonight!"
2. **创意短信：**
Write a haiku about autumn and send it to my number +11234567890
3. **问候语：**
Send a birthday greeting to +11234567890
## 📝 脚本参考
- `npm run build` -将TypeScript构建为JavaScript
- `npm run start:mcp` -启动MCP服务器模式
- `npm run start:web` -启动web API服务器模式
- `npm run dev:web` -开发模式（重建+启动web服务器）
- `npm run watch` -观察TypeScript文件的变化
## ⚠️ 重要提示
1. **电话号码格式**：所有电话号码必须采用E.164格式（例如+1234567890）
1. **Twilio试用账户**：只能向经过验证的电话号码发送消息
1. **速率限制**：了解您的Twilio帐户的费率限制和定价
1. **安全**：确保您的Twilio凭据安全，永远不要将其提交给版本控制
1. **环境变量**：使用 `.env` 本地开发文件，通过云部署平台设置
## 🐛 故障排除
### 常见错误和解决方案：
1. **“电话号码必须采用E.164格式”**
- 确保电话号码以“+”开头，并包含国家代码
1. **“凭据无效”/“accountSid必须以AC开头”**
- 验证您的帐户ID和AUTH_TOKEN [Twilio控制台](https://console.twilio.com)
- 确保环境变量已正确加载
1. **“无效的“收件人”电话号码”**
- 对于试用帐户：在Twilio控制台中验证目标号码
- 对于付费账户：确保数字格式正确
1. **“环境变量是必需的”**
- 检查一下 `.env` 文件存在并包含所有必需的变量
- 对于云部署，确保在平台设置中设置了环境变量
## 🤝 贡献
欢迎投稿！在提交pull请求之前，请阅读我们的贡献指南。
## 📄 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
## 🔐 安全
请不要在GitHub issues或pull请求中包含任何敏感信息（如电话号码或Twilio凭据）。