Principiante

MCP Server — AI Agents

Conecta la API eCMR con Claude Desktop, Cursor, Cline y otros asistentes AI mediante el servidor MCP oficial de Cargoffer.

¿Qué es el MCP Server?

El @cargoffer/ecmr-mcp es un servidor MCP (Model Context Protocol) que expone la API eCMR como herramientas llamables por asistentes AI. Esto permite que Claude Desktop, Cursor, Cline, Continue y otros clientes MCP gestionen documentos de transporte electrónico en lenguaje natural.

En lugar de escribir llamadas REST manualmente, un agente AI puede:

"Crea un eCMR para el envío de 24 palets de Madrid a Barcelona"
"Firma la recogida del eCMR VIGACOQjFHn"
"Muéstrame todos los eCMRs pendientes de firma"

Instalación

Obtener una API Key

El MCP Server necesita una API Key de la plataforma eCMR. Puedes crearla directamente desde la API:

# 1. Primero inicia sesión con tu usuario administrador:
POST https://ecmr.api.pro.cargoffer.com/auth/login 📖
{ "email": "admin@miempresa.com", "password": "tu-password" }
# → Obtienes un JWT token

# 2. Crea una API Key con ese token:
POST https://ecmr.api.pro.cargoffer.com/apikeys 📖
Authorization: Bearer <JWT_del_paso_1>
{ "type": "admin" }
# → La respuesta incluye tu API Key (guárdala, solo se muestra una vez)

Si aún no tienes cuenta en el sistema, revisa el tutorial completo de Conexión a la API que incluye registro, login y creación de API Key paso a paso.

🔑 La API Key se pasa como query param: ?apikey=CLAVE_API o como variable de entorno ECMR_API_KEY en el MCP Server. Se guarda hasheada (bcrypt) en la base de datos — si la pierdes, crea una nueva con POST /apikeys.

Configurar en Claude Desktop

Añade esta configuración a tu claude_desktop_config.json:

{
  "mcpServers": {
    "ecmr": {
      "command": "npx",
      "args": ["-y", "@cargoffer/ecmr-mcp"],
      "env": {
        "ECMR_API_KEY": "tu-api-key-aqui"
      }
    }
  }
}

Reemplaza tu-api-key-aqui con tu API Key real.

Configurar en Cursor / Cline / Continue

En Cursor, añade al archivo .cursor/mcp.json de tu proyecto:

{
  "mcpServers": {
    "ecmr": {
      "command": "npx",
      "args": ["-y", "@cargoffer/ecmr-mcp"],
      "env": {
        "ECMR_API_KEY": "tu-api-key-aqui"
      }
    }
  }
}

Para Cline (VS Code extension): misma configuración en cline_mcp_settings.json.

Herramientas disponibles (30+)

Categoría	Tool	Descripción
🔐 Auth	`ecmr_auth_login`	Autenticar y obtener JWT
🔐 Auth	`ecmr_auth_register`	Registrar nueva cuenta
📍 Addresses	`ecmr_addresses_list, _create, _get, _update, _delete`	Gestión completa de direcciones
👤 Drivers	`ecmr_drivers_list, _create, _get, _delete`	Gestión de conductores
🚛 Vehicles	`ecmr_vehicles_list, _create, _get, _delete`	Gestión de vehículos
📄 eCMR Core	`ecmr_list, _create, _get, _update, _delete, _lock`	Ciclo de vida del eCMR
✍️ Signatures	`ecmr_sign_sender, _pickup, _delivery`	Firma digital por rol
📎 Documents	`ecmr_documents_list, _upload, _delete`	Documentos adjuntos
📦 Pallets	`ecmr_pallets_add, _list, _update, _remove, _clear`	Gestión de pallets
📱 QR	`ecmr_qr_get, _details, _download`	Acceso y descarga vía QR
📄 PDF	`ecmr_render_html`	Vista previa HTML del eCMR

🔧 Ejemplo: Pídele a tu AI: "Crea un eCMR para 10 palets desde mi almacén de Madrid hasta Barcelona, asigna el vehículo 1234ABC y el conductor Carlos López, y luego firma la recogida."

Publicación npm

El paquete está disponible en npm como @cargoffer/ecmr-mcp. Se ejecuta con npx sin necesidad de instalación previa.

# Ejecutar directamente (sin instalar)
npx -y @cargoffer/ecmr-mcp

Repositorio y recursos

GitHub: cargoffer/ecmr-mcp — Código fuente y documentación
npm: @cargoffer/ecmr-mcp — Paquete publicado
Model Context Protocol — Especificación MCP