创蓝 253 MCP Server

创蓝 253 短信平台 MCP 服务器 - 企业级实现

基于 FastMCP 框架构建，提供短信发送、余额查询、状态报告等功能的标准化 MCP 接口。

特性

• 企业级代码质量
• 完整的类型注解
• Pydantic 数据验证
• 异步 I/O 支持
• 完善的错误处理
• 完整的测试覆盖
• 详细的文档

快速开始

1. 环境要求

• Python >= 3.10
• pip >= 21.0

2. 安装依赖

pip install -r requirements.txt

3. 配置

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入创蓝账号信息

4. 运行

# 方式一：使用 uvicorn 运行
fastmcp run src/chuanglan_mcp/server.py

# 方式二：直接运行
python -m chuanglan_mcp

目录结构

chuanglan-mcp/
├── src/
│   └── chuanglan_mcp/
│       ├── __init__.py          # 包初始化
│       ├── __main__.py          # 入口点
│       ├── server.py            # MCP 服务器定义
│       ├── client.py            # 创蓝 API 客户端
│       ├── config.py            # 配置管理
│       ├── models.py            # 数据模型
│       └── exceptions.py        # 自定义异常
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest 配置
│   ├── test_client.py           # 客户端测试
│   ├── test_server.py           # 服务器测试
│   └── test_models.py           # 模型测试
├── examples/
│   ├── basic_usage.py           # 基础使用示例
│   └── advanced_usage.py        # 高级使用示例
├── docs/
│   ├── api.md                   # API 文档
│   └── deployment.md            # 部署文档
├── scripts/
│   ├── lint.py                  # 代码检查
│   └── test.py                  # 运行测试
├── .env.example                 # 环境变量示例
├── .gitignore
├── LICENSE
├── README.md
├── README_EN.md                 # 英文文档
├── pyproject.toml               # 项目配置
├── requirements.txt             # 依赖
├── requirements-dev.txt         # 开发依赖
└── setup.cfg                    # 安装配置

MCP 工具

工具	描述	参数
send_template_sms	发送模板短信	phone, template_id, params, extend, batch_id
query_balance	查询余额	无
query_status	查询发送状态	task_id, start_time, end_time, page, page_size

配置说明

环境变量

变量	必填	说明
CHUANGLAN_ACCOUNT	是	创蓝 API 账号
CHUANGLAN_PASSWORD	是	创蓝 API 密码
CHUANGLAN_SMS_URL	否	短信发送地址（默认：https://smssh1.253.com/msg/json）
CHUANGLAN_BALANCE_URL	否	余额查询地址（默认：https://smssh1.253.com/msg/balance/json）
CHUANGLAN_STATUS_URL	否	状态报告地址（默认：https://smssh1.253.com/msg/status/json）
REQUEST_TIMEOUT	否	请求超时时间（默认：30 秒）

开发指南

运行测试

# 安装开发依赖
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_server-*.whl

魔搭社区发布

1. 访问 魔搭社区 注册账号
2. 创建新模型
3. 上传项目文件
4. 填写模型卡片
5. 发布版本

详细步骤请参考 docs/deployment.md

API 文档

完整的 API 文档请参考 docs/api.md

常见问题

Q: 如何获取创蓝账号？

A: 访问 创蓝 253 官网 注册账号

Q: 模板 ID 如何获取？

A: 登录创蓝控制台，创建短信模板并审核通过后获得

Q: 返回码 102 是什么意思？

A: 密码错误，请检查密码配置

相关资源

• 创蓝 253 官网
• 创蓝 API 文档
• FastMCP 文档
• 魔搭社区
• MCP 协议

许可证

MIT License

联系方式

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