cdek-mcp

MCP-Server für die CDEK-Versand-API (v2). 16 Tools decken den gesamten Versandlebenszyklus ab: Tarifberechnung, Auftragsverwaltung, Sendungsverfolgung, Standortsuche, Kurierabholung, Barcode-/Belegerzeugung und Webhooks.

Tools (16)

Tarife

Aufträge

Sendungsverfolgung

Standorte

Barcode & Druck

Kurierabholung

Webhooks

Related MCP server: Parcel MCP Server

Schnellstart

Claude Desktop

~/.config/claude/claude_desktop_config.json (macOS) oder %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 oder .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

Für Web-Bereitstellungen verwenden Sie das --http-Flag oder die Umgebungsvariable HTTP_PORT:

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

Endpunkte:

• POST /mcp — MCP JSON-RPC

• GET /mcp — SSE-Stream

• DELETE /mcp — Sitzungsbeendigung

• GET /health — Health-Check

Umgebungsvariablen

Holen Sie sich Ihre API-Schlüssel: CDEK Dashboard > Integration > API-Schlüssel.

Sandbox-Modus

Setzen Sie CDEK_SANDBOX=true, um die CDEK-Testumgebung (api.edu.cdek.ru) zu verwenden. Die Produktion verwendet api.cdek.ru.

CDEK stellt ein gemeinsames Sandbox-Konto für Integrationstests bereit:

• Client-ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• Client-Secret: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK rotiert dieses gemeinsame Testkonto von Zeit zu Zeit. Wenn Sie OAuth token error (HTTP 401) … invalid_client erhalten, wurde das öffentliche Paar rotiert — fordern Sie Ihre eigenen Sandbox-Schlüssel über das CDEK-Integrationsdashboard an (lk.cdek.ru → Integration → API-Schlüssel).

Authentifizierung

OAuth-2.0-Client-Credentials-Ablauf, übernommen von der OAuthStrategy in @theyahia/mcp-core:

• Automatischer Token-Abruf bei der ersten Anfrage

• Token-Caching mit proaktivem Refresh kurz vor Ablauf

• Deduplizierung gleichzeitiger Anfragen (ein einzelner laufender Token-Refresh wird gemeinsam genutzt)

• Automatischer Wiederholungsversuch bei 401 mit Token-Invalidierung

E-Commerce-Stack

Kombinieren Sie es mit anderen russian-mcp-Servern für einen vollständigen E-Commerce-KI-Stack:

Teil der russian-mcp-Serie.

Demo-Prompts

1. „Wie viel kostet es, ein 2-kg-Paket von Moskau nach Sankt Petersburg zu versenden?“ Verwendet get_cities, um Stadtcodes zu finden, dann calculate_tariff_list, um alle verfügbaren Tarife zu vergleichen.

2. „Finde den nächstgelegenen CDEK-Abholpunkt am Roten Platz“ Verwendet get_cities, um den Moskauer city_code aufzulösen, dann list_delivery_points mit latitude: 55.7539, longitude: 37.6208, radius_km: 5 — die Ergebnisse werden auf den Radius gefiltert und nach Entfernung sortiert (jeweils mit координаты und расстояние_км versehen).

3. „Erstelle einen Auftrag, um ein Buch von Kasan nach Nowosibirsk zu senden, plane die Kurierabholung und drucke den Beleg“ Verwendet create_order, dann create_courier_pickup, um die Abholung zu planen, und print_receipt für den Frachtbrief.

Entwicklung

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)

Führen Sie den Server lokal gegen die CDEK-Sandbox (api.edu.cdek.ru) aus — verwenden Sie das gemeinsame Testpaar aus Sandbox-Modus oder Ihre eigenen Sandbox-Schlüssel:

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

Siehe CHANGELOG.md für Versionshinweise.

Lizenz

MIT