cdek-mcp

CDEK 배송 API(v2)용 MCP 서버입니다. 16가지 도구로 배송 프로세스 전반을 지원합니다: 요금 계산, 주문 관리, 배송 추적, 위치 검색, 택배 기사 픽업, 바코드/영수증 생성, 웹훅.

도구 (16)

요금

주문

추적

위치

바코드 및 인쇄

택배 기사 픽업

웹훅

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 전송

웹 배포의 경우 --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 대시보드 > 통합 > API 키.

샌드박스 모드

CDEK_SANDBOX=true로 설정하면 CDEK 테스트 환경(api.edu.cdek.ru)을 사용합니다. 프로덕션에서는 api.cdek.ru를 사용합니다.

CDEK는 통합 테스트를 위해 공유 샌드박스 계정을 제공합니다:

• 클라이언트 ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• 클라이언트 시크릿: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK는 이 공유 테스트 계정을 수시로 교체합니다. OAuth token error (HTTP 401) … invalid_client 오류가 발생하면 공개 키가 교체된 것입니다. CDEK 통합 대시보드(lk.cdek.ru → 통합 → API 키)에서 직접 샌드박스 키를 요청하세요.

인증

OAuth 2.0 클라이언트 자격 증명(Client Credentials) 흐름은 @theyahia/mcp-core의 OAuthStrategy가 처리합니다:

• 첫 번째 요청 시 자동 토큰 획득

• 만료 직전 사전 갱신을 포함한 토큰 캐싱

• 동시 요청 중복 제거(진행 중인 단일 토큰 갱신 공유)

• 토큰 무효화와 함께 401 자동 재시도

이커머스 스택

완전한 이커머스 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