# chuanglan_mcp

**Repository Path**: missj_admin/chuanglan_mcp

## Basic Information

- **Project Name**: chuanglan_mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 创蓝 253 MCP Server (V2 API)

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-black.svg)](https://github.com/astral-sh/ruff)

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

## 快速开始

### 1. 环境要求

- Python >= 3.10
- pip >= 21.0

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境变量

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

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```bash
# 必填：创蓝 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 种传输方式：**

```bash
# 方式一：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
```

**客户端配置示例：**

```json
// 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 - 发送模板短信

```python
# 传入账号密码
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 - 查询余额

```python
# 传入账号密码
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. **配置合理的超时和重试策略**
   ```bash
   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](docs/api-reference/error-codes.md)

## 开发指南

### 运行测试

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

# 运行所有测试
pytest tests/

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

### 代码检查

```bash
# 运行 Ruff 检查
ruff check src/

# 运行 Ruff 格式化
ruff format src/

# 运行 mypy 类型检查
mypy src/
```

## 部署

### 本地开发

```bash
pip install -e .
```

### 生产环境

```bash
# 构建包
pip install build
python -m build

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

### Docker 部署

```bash
# 构建镜像
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](docs/deployment/docker.md)

## 相关资源

- [创蓝 V2 API 文档](https://doc.chuanglan.com/document/HAQYSZKH9HT5Z50L)
- [创蓝 253 官网](https://www.chuanglan.com/)
- [FastMCP 文档](https://github.com/jlowin/fastmcp)
- [MCP 协议](https://modelcontextprotocol.io/)
- [Pydantic v2 文档](https://docs.pydantic.dev/latest/)

## 许可证

MIT License

## 联系方式

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