cdek-mcp

用于 CDEK 配送 API（v2）的 MCP 服务器。16 个工具涵盖完整的配送生命周期：运费计算、订单管理、物流追踪、地点搜索、快递员取件、条码/收据生成和 Webhooks。

工具（16）

运费方案

订单

物流追踪

地点

条码与打印

快递员取件

Webhooks

Related MCP server: Parcel MCP Server

快速开始

Claude Desktop

~/.config/claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "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：

{
  "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：

{
  "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"
      }
    }
  }
}

流式 HTTP 传输

对于 Web 部署，请使用 --http 标志或 HTTP_PORT 环境变量：

HTTP_PORT=3000 npx @theyahia/cdek-mcp --http

端点：

• POST /mcp — MCP JSON-RPC

• GET /mcp — SSE 流

• DELETE /mcp — 会话终止

• GET /health — 健康检查

环境变量

获取你的 API 密钥：CDEK Dashboard > 集成 > API 密钥。

沙箱模式

设置 CDEK_SANDBOX=true 以使用 CDEK 测试环境（api.edu.cdek.ru）。生产环境使用 api.cdek.ru。

CDEK 发布了一个共享沙箱账户，用于集成测试：

• Client ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• Client Secret: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK 会不时轮换这个共享测试账户。如果你收到 OAuth token error (HTTP 401) … invalid_client，说明公共密钥对已被轮换——请从 CDEK 集成控制台（lk.cdek.ru → 集成 → API 密钥）申请你自己的沙箱密钥。

身份验证

OAuth 2.0 客户端凭证（Client Credentials）流程，由 @theyahia/mcp-core 中的 OAuthStrategy 处理：

• 首次请求时自动获取令牌

• 缓存令牌并在过期前主动刷新

• 并发请求去重（共享同一个进行中的令牌刷新）

• 收到 401 时自动重试并使令牌失效

电商技术栈

与其他 russian-mcp 服务器搭配使用，构建完整的电商 AI 技术栈：

属于 russian-mcp 系列。

演示提示词

1. “把一件 2kg 的包裹从莫斯科寄到圣彼得堡要多少钱？” 使用 get_cities 查找城市代码，然后使用 calculate_tariff_list 比较所有可用的运费方案。

2. “查找距离红场最近的 CDEK 取件点” 使用 get_cities 解析莫斯科的 city_code，然后使用 list_delivery_points，参数为 latitude: 55.7539、longitude: 37.6208、radius_km: 5——结果按半径过滤并按距离排序（每个结果都标注了 координаты 和 расстояние_км）。

3. “创建一个订单，将一本书从喀山寄到新西伯利亚，安排快递员取件，并打印收据” 使用 create_order，然后使用 create_courier_pickup 安排上门取件，再使用 print_receipt 生成运单。

开发

git clone https://github.com/theYahia/cdek-mcp.git
cd cdek-mcp
npm install

npm run lint        # ESLint (flat config)
npm run typecheck   # tsc --noEmit
npm run build       # emit dist/
npm test            # unit tests (vitest)
npm run test:e2e    # e2e smoke test (lists tools, no real credentials)

在本地运行服务器，连接 CDEK 沙箱环境（api.edu.cdek.ru）——使用沙箱模式中的共享测试密钥对，或使用你自己的沙箱密钥：

CDEK_SANDBOX=true \
CDEK_CLIENT_ID=<YOUR_SANDBOX_CLIENT_ID> \
CDEK_CLIENT_SECRET=<YOUR_SANDBOX_CLIENT_SECRET> \
npm run dev

查看 CHANGELOG.md 获取发布说明。

许可证

MIT