内容
# CDEK 物流服务器
[](https://www.npmjs.com/package/@theyahia/cdek-mcp)
[](https://github.com/theYahia/cdek-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
CDEK 物流服务器，提供完整的物流生命周期支持，包括运费计算、订单管理、货物跟踪、地点搜索、快递取货、条码/收据生成以及 Webhooks 等功能。
## 工具列表
### 运费计算工具
| 工具 | 描述 |
|------|-------------|
| `calculate_tariff` | 计算指定运费的配送成本和时间 |
| `calculate_tariff_list` | 获取指定线路的所有可用运费及价格 |
### 订单管理工具
| 工具 | 描述 |
|------|-------------|
| `create_order` | 创建包含寄件人、收件人和包裹的配送订单 |
| `get_order` | 通过 UUID 获取订单详情和状态 |
| `delete_order` | 通过 UUID 取消/删除订单 |
| `list_orders` | 按日期范围、IM 号或 CDEK 运单号搜索/筛选订单 |
### 货物跟踪工具
| 工具 | 描述 |
|------|-------------|
| `track_shipment` | 通过 CDEK 运单号跟踪货物 |
### 地点搜索工具
| 工具 | 描述 |
|------|-------------|
| `get_cities` | 按名称、邮政编码或国家搜索城市目录 |
| `get_regions` | 按国家或名称搜索地区目录 |
| `list_delivery_points` | 按城市或 GPS 坐标查找取货点和包裹柜 |
### 条码和打印工具
| 工具 | 描述 |
|------|-------------|
| `generate_barcode` | 为订单生成条码/标签 |
| `print_receipt` | 为订单生成收据/运单 PDF |
### 快递取货工具
| 工具 | 描述 |
|------|-------------|
| `create_courier_pickup` | 为订单安排快递取货 |
| `get_courier_pickup` | 查询快递取货请求状态 |
### Webhooks 工具
| 工具 | 描述 |
|------|-------------|
| `create_webhook` | 注册订单状态更新或配送照片的 Webhook |
| `delete_webhook` | 通过 UUID 删除 Webhook 订阅 |
## 快速开始
### Claude Desktop
`~/.config/claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"cdek": {
"command": "npx",
"args": ["-y", "@theyahia/cdek-mcp"],
"env": {
"CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
"CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
"CDEK_SANDBOX": "true"
}
}
}
}
```
### Cursor / Windsurf
`.cursor/mcp.json` 或 `.windsurf/mcp.json`：
```json
{
"mcpServers": {
"cdek": {
"command": "npx",
"args": ["-y", "@theyahia/cdek-mcp"],
"env": {
"CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
"CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
"CDEK_SANDBOX": "true"
}
}
}
}
```
### VS Code (Copilot)
`.vscode/mcp.json`：
```json
{
"servers": {
"cdek": {
"command": "npx",
"args": ["-y", "@theyahia/cdek-mcp"],
"env": {
"CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
"CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
"CDEK_SANDBOX": "true"
}
}
}
}
```
### Streamable HTTP Transport
适用于 Web 部署，使用 `--http` 标志或 `HTTP_PORT` 环境变量：
```bash
HTTP_PORT=3000 npx @theyahia/cdek-mcp --http
```
端点：
- `POST /mcp` — MCP JSON-RPC
- `GET /mcp` — SSE 流
- `DELETE /mcp` — 会话终止
- `GET /health` — 健康检查
## 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `CDEK_CLIENT_ID` | 是 | CDEK 控制面板中的客户端 ID |
| `CDEK_CLIENT_SECRET` | 是 | CDEK 控制面板中的客户端密钥 |
| `CDEK_SANDBOX` | 否 | `true` 使用沙盒环境（api.edu.cdek.ru） |
| `HTTP_PORT` | 否 | HTTP 传输的端口（启用 HTTP 模式） |
获取 API 密钥：[CDEK 控制面板](https://lk.cdek.ru) > 集成 > API 密钥。
## 沙盒模式
设置 `CDEK_SANDBOX=true` 使用 CDEK 测试环境。沙盒环境使用测试凭证和 `api.edu.cdek.ru` 端点。
测试凭证：
- 客户端 ID：`EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI`
- 客户端密钥：`PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh`
生产环境使用 `api.cdek.ru`。
## 身份验证
OAuth 2.0 客户端凭证流。TokenManager 处理：
- 首次请求自动获取令牌
- 令牌缓存（3600 秒 TTL）
- 提前 60 秒主动刷新令牌
- 并发请求去重
- 401 状态码下令牌失效自动重试
## 电商栈
与其他俄语 MCP 服务器配对，构建完整的电商 AI 栈：
| 服务器 | 用途 |
|--------|---------|
| **cdek-mcp** | 物流与配送 |
| [dadata-mcp](https://github.com/theYahia/dadata-mcp) | 地址验证、公司查找 |
[russian-mcp](https://github.com/theYahia?tab=repositories&q=mcp) 系列的一部分。
## 演示提示
1. **"从莫斯科到圣彼得堡寄送 2kg 包裹的费用是多少？"**
使用 `get_cities` 查找城市代码，然后使用 `calculate_tariff_list` 比较所有可用运费。
2. **"查找距离红场最近的 CDEK 取货点"**
使用 `list_delivery_points` 和 GPS 坐标（纬度：55.7539，经度：37.6208）查找附近地点。
3. **"创建从 Kazan 到 Novosibirsk 的订单，安排快递取货并打印收据"**
使用 `create_order`，然后使用 `create_courier_pickup` 安排取货，并使用 `print_receipt` 生成运单。
## 开发
```bash
git clone https://github.com/theYahia/cdek-mcp.git
cd cdek-mcp
npm install
npm run build
npm test
```
## 许可证
MIT
