创蓝 253 MCP Server (V2 API)

企业级创蓝 253 短信平台 MCP 服务器 - 基于 FastMCP 框架构建，提供短信发送、余额查询等功能的标准化 MCP 接口。

快速开始

1. 环境要求

• Python >= 3.10
• pip >= 21.0

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

复制 .env.example 为 .env 并填写配置：

cp .env.example .env

编辑 .env 文件：

# 必填：创蓝 API 账号密码（如果使用环境变量方式）
CHUANGLAN_ACCOUNT=your_account
CHUANGLAN_PASSWORD=your_password

# API 地址配置（可选）
CHUANGLAN_SMS_URL=https://smssh.253.com/msg/sms/v2/tpl/send
CHUANGLAN_BALANCE_URL=https://smssh.253.com/msg/balance/v2/query

4. 运行服务

支持 4 种传输方式：

# 方式一：stdio（默认，用于 Claude Desktop）
python -m chuanglan_mcp.server

# 方式二：SSE（Server-Sent Events，用于远程服务器）
python -m chuanglan_mcp.server --transport sse --port 8000

# 方式三：Streamable HTTP
python -m chuanglan_mcp.server --transport streamable-http --port 8000

# 方式四：HTTP POST
python -m chuanglan_mcp.server --transport http --port 8000

客户端配置示例：

// stdio 配置（Claude Desktop、Cursor）
{
  "mcpServers": {
    "chuanglan": {
      "command": "python",
      "args": ["-m", "chuanglan_mcp.server"],
      "env": {
        "CHUANGLAN_ACCOUNT": "your_account",
        "CHUANGLAN_PASSWORD": "your_password"
      }
    }
  }
}

// SSE 配置（远程服务器）
{
  "mcpServers": {
    "chuanglan": {
      "type": "sse",
      "url": "http://your-server:8000/sse"
    }
  }
}

// Streamable HTTP 配置
{
  "mcpServers": {
    "chuanglan": {
      "type": "streamable-http",
      "url": "http://your-server:8000/streamable-http"
    }
  }
}

目录结构

chuanglan-mcp/
├── src/chuanglan_mcp/
│   ├── __init__.py          # 包初始化，导出公共接口
│   ├── __main__.py          # 入口点
│   ├── server.py            # MCP 服务器定义
│   ├── core/                # 核心组件
│   │   ├── __init__.py
│   │   ├── client.py        # 创蓝 API 客户端 (V2)
│   │   ├── config.py        # 配置管理
│   │   └── exceptions.py    # 自定义异常
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── request.py       # 请求模型
│   │   └── response.py      # 响应模型
│   └── tools/               # 工具模块
│       ├── __init__.py
│       ├── sms.py           # 短信工具
│       └── balance.py       # 余额工具
├── tests/
├── docs/
├── .env.example
├── README.md
├── pyproject.toml
└── requirements.txt

MCP 工具

工具	描述	参数
send_template_sms	发送模板短信	phone, template_id, params, account, password, signature, report, callback_url, uid, extend
query_balance	查询余额	account, password

工具示例

send_template_sms - 发送模板短信

# 传入账号密码
result = await send_template_sms(
    phone="13800138000",
    template_id="1021143438",
    params=[{"param1": "张三", "param2": "13"}],
    account="N6000001",
    password="your_password"
)

# 使用环境变量配置的账号
result = await send_template_sms(
    phone="13800138000",
    template_id="1021143438",
    params=[{"param1": "张三", "param2": "13"}]
)

query_balance - 查询余额

# 传入账号密码
result = await query_balance(
    account="N6000001",
    password="your_password"
)

# 使用环境变量配置的账号
result = await query_balance()

配置说明

环境变量

变量	必填	说明
CHUANGLAN_SMS_URL	否	短信发送地址（默认：https://smssh.253.com/msg/sms/v2/tpl/send）
CHUANGLAN_BALANCE_URL	否	余额查询地址（默认：https://smssh.253.com/msg/balance/v2/query）
CHUANGLAN_STATUS_URL	否	状态报告查询地址（默认：https://smssh.253.com/msg/status/v2/query）
CHUANGLAN_ACCOUNT	否	创蓝 API 账号（可选，不传则工具调用时需传入）
CHUANGLAN_PASSWORD	否	创蓝 API 密码（可选，不传则工具调用时需传入）
REQUEST_TIMEOUT	否	请求超时时间（默认：30 秒）
LOG_LEVEL	否	日志级别（默认：INFO）

凭证优先级

1. 工具调用时传入 account 和 password → 使用传入的值
2. 未传入 → 使用环境变量 CHUANGLAN_ACCOUNT 和 CHUANGLAN_PASSWORD
3. 都未配置 → 抛出错误提示用户配置

安全最佳实践

保护敏感凭证

⚠️ 切勿将 .env 文件提交到版本控制系统

项目已配置 .gitignore 自动忽略 .env 文件。请确保：

1. 使用 .env.example 作为配置模板
2. 生产环境使用环境变量或密钥管理服务
3. 定期轮换 API 凭证

生产环境部署建议

1. 使用密钥管理服务

   • AWS Secrets Manager
   • Azure Key Vault
   • HashiCorp Vault

2. 配置合理的超时和重试策略

   REQUEST_TIMEOUT=30
   

V2 API 说明

接口地址

https://smssh.253.com/msg/sms/v2/tpl/send

请求参数

参数	类型	必填	说明
account	String	是	API 账号
password	String	否	API 密码（使用签名鉴权时可不传）
phoneNumbers	String	是	手机号，逗号分隔，最多 1000 个
templateId	String	是	模板 ID
templateParamJson	String	否	模板变量参数，JSON 数组格式
signature	String	否	短信签名
report	String	否	状态回执开关，true/false
callbackUrl	String	否	状态回执回调地址
uid	String	否	自定义参数，最大 256 位
extend	String	否	扩展码

响应参数

参数	类型	说明
code	String	返回码，"000000" 表示成功
msgId	String	消息 ID（32 位纯数字）
time	String	响应时间
successNum	String	提交成功数量
failNum	String	提交失败数量
errorMsg	String	错误描述

常见返回码

返回码	说明
000000	提交成功
101	无此用户
102	密码错
104	系统忙
107	包含错误的手机号码
109	无发送额度
116	签名不合法或未带签名
129	JSON 格式错误
152	模板不存在

完整返回码列表请参考 docs/api-reference/error-codes.md

开发指南

运行测试

# 安装开发依赖
pip install -r requirements-dev.txt

# 运行所有测试
pytest tests/

# 运行测试并生成覆盖率报告
pytest tests/ --cov=chuanglan_mcp --cov-report=html

代码检查

# 运行 Ruff 检查
ruff check src/

# 运行 Ruff 格式化
ruff format src/

# 运行 mypy 类型检查
mypy src/

部署

本地开发

pip install -e .

生产环境

# 构建包
pip install build
python -m build

# 安装
pip install dist/chuanglan_mcp-*.whl

Docker 部署

# 构建镜像
docker build -t chuanglan-mcp:latest .

# 运行容器
docker run -d \
  -e CHUANGLAN_ACCOUNT=your_account \
  -e CHUANGLAN_PASSWORD=your_password \
  chuanglan-mcp:latest

📖 详细文档：docs/deployment/docker.md

相关资源

• 创蓝 V2 API 文档
• 创蓝 253 官网
• FastMCP 文档
• MCP 协议
• Pydantic v2 文档

许可证

MIT License

联系方式

• 技术支持：support@chuanglan.com
• 项目地址：https://github.com/chuanglan/chuanglan-mcp-server