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

Streamable HTTP Transport

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 のテスト環境（api.edu.cdek.ru）を使用するには、CDEK_SANDBOX=true を設定します。本番環境では api.cdek.ru を使用します。

CDEK は統合テスト用の共有サンドボックスアカウントを公開しています：

• クライアント ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• クライアントシークレット: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK はこの共有テストアカウントを随時ローテーションします。OAuth token error (HTTP 401) … invalid_client が発生した場合、公開ペアはローテーション済みです — CDEK 統合ダッシュボード（lk.cdek.ru → 統合 → API キー）から独自のサンドボックスキーをリクエストしてください。

認証

OAuth 2.0 クライアントクレデンシャルフローは、@theyahia/mcp-core の OAuthStrategy によって処理されます：

• 最初のリクエスト時に自動でトークンを取得

• 有効期限直前にプロアクティブに更新するトークンキャッシュ

• 同時リクエストの重複排除（実行中のトークン更新は 1 つに共有されます）

• 401 発生時にトークンを無効化し自動リトライ

Eコマーススタック

完全な Eコマース AI スタックを構築するには、他の russian-mcp サーバーと組み合わせて使用します：

russian-mcp シリーズの一部です。

デモプロンプト

1. 「モスクワからサンクトペテルブルクへ 2kg の小包を送るといくらかかりますか？」 get_cities を使用して都市コードを検索し、calculate_tariff_list で利用可能なすべての料金プランを比較します。

2. 「赤の広場に最も近い CDEK 受け取り場所を探す」 get_cities を使用してモスクワの city_code を特定し、latitude: 55.7539、longitude: 37.6208、radius_km: 5 を指定して list_delivery_points を使用します。結果は半径内に絞り込まれ、距離順に並べ替えられます（各結果には координаты と расстояние_км が注記されます）。

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