cdek-mcp

Servidor MCP para la API de entrega de CDEK (v2). 16 herramientas que cubren todo el ciclo de vida de la entrega: cálculo de tarifas, gestión de pedidos, seguimiento de envíos, búsqueda de ubicaciones, recogida por mensajero, generación de códigos de barras/recibos y webhooks.

Herramientas (16)

Tarifas

Pedidos

Seguimiento

Ubicaciones

Código de barras e impresión

Recogida por mensajero

Webhooks

Related MCP server: Parcel MCP Server

Inicio rápido

Claude Desktop

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

Transporte HTTP Streamable

Para despliegues web, usa el flag --http o la variable de entorno HTTP_PORT:

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

Endpoints:

• POST /mcp — MCP JSON-RPC

• GET /mcp — flujo SSE

• DELETE /mcp — terminación de sesión

• GET /health — comprobación de salud

Variables de entorno

Obtén tus claves de API: Panel de CDEK > Integración > Claves de API.

Modo sandbox

Establece CDEK_SANDBOX=true para usar el entorno de pruebas de CDEK (api.edu.cdek.ru). En producción se usa api.cdek.ru.

CDEK publica una cuenta sandbox compartida para pruebas de integración:

• Client ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• Client Secret: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK rota esta cuenta de prueba compartida de vez en cuando. Si obtienes OAuth token error (HTTP 401) … invalid_client, el par público ha sido rotado — solicita tus propias claves de sandbox desde el panel de integración de CDEK (lk.cdek.ru → Integración → Claves de API).

Autenticación

Flujo de credenciales de cliente OAuth 2.0, gestionado por la OAuthStrategy en @theyahia/mcp-core:

• Adquisición automática del token en la primera solicitud

• Almacenamiento en caché del token con renovación proactiva poco antes de que caduque

• Deduplicación de solicitudes concurrentes (una única renovación de token en curso se comparte)

• Reintento automático en caso de 401 con invalidación del token

Stack de comercio electrónico

Combínalo con otros servidores russian-mcp para un stack completo de IA para comercio electrónico:

Parte de la serie russian-mcp.

Prompts de demostración

1. «¿Cuánto cuesta enviar un paquete de 2kg de Moscú a San Petersburgo?» Usa get_cities para encontrar los códigos de ciudad y luego calculate_tariff_list para comparar todas las tarifas disponibles.

2. «Encuentra el punto de recogida de CDEK más cercano a la Plaza Roja» Usa get_cities para resolver el city_code de Moscú y luego list_delivery_points con latitude: 55.7539, longitude: 37.6208, radius_km: 5 — los resultados se filtran por el radio y se ordenan por distancia (cada uno anotado con координаты y расстояние_км).

3. «Crea un pedido para enviar un libro de Kazán a Novosibirsk, programa la recogida por mensajero e imprime el recibo» Usa create_order, luego create_courier_pickup para programar la recogida y print_receipt para la guía.

Desarrollo

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)

Ejecuta el servidor localmente contra el sandbox de CDEK (api.edu.cdek.ru) — usa el par de prueba compartido de Modo sandbox o tus propias claves de sandbox:

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

Consulta CHANGELOG.md para las notas de la versión.

Licencia

MIT