FreightUtils MCP Server

11 herramientas de logística de carga para agentes de IA: consulta de mercancías peligrosas ADR (2,939 entradas UN, UNECE ADR 2025), búsqueda de códigos SA (6,940 códigos, WCO SA 2022), códigos de aerolíneas (6,352 con prefijos AWB), calculadoras de LDM/CBM/peso facturable, ajuste de pallets, capacidad de contenedores, INCOTERMS 2020, conversor de unidades y calculadora de exención ADR 1.1.3.6. APIs REST gratuitas + endpoint MCP remoto.

GitHub

Documentación

Servidor MCP de FreightUtils

La capa de referencia neutral de flete para agentes de IA.

FreightUtils es la capa de referencia neutral de flete para agentes de IA: datos de mercancías peligrosas, aduanas, ubicaciones y cálculos de flete respaldados por fuentes primarias (ADR 2025 / UNECE, HS 2022 / OMC, prefijos de aerolíneas regulados por IATA) que un agente puede consultar y citar. Neutral por diseño: no hay flete que vender ni transportista que promocionar: una consulta devuelve lo que dice la fuente nombrada, con la cita adjunta para que un agente pueda inspeccionarla en lugar de tomar nuestra palabra, independientemente de quién transporte la carga.

Este servidor de Protocolo de Contexto de Modelo brinda a los agentes de IA acceso a 25 herramientas de cálculo y referencia de flete, que cubren flete por carretera, aéreo y marítimo. Creado por un planificador de transporte de flete certificado ADR del Reino Unido.

Cada respuesta cita su fuente: un bloque _source con la autoridad, edición, licencia cuando corresponde y un estado de verificación que un agente puede leer — y las herramientas son deterministas, no respuestas generadas. Solo referencia: nunca asesoramiento legal, de reserva o de trámite, y los resultados indican cuándo se requiere revisión humana (validate es solo validación estructural de dígitos de control; un ics2_check limpio no es aceptación ENS; las cifras de emisiones son estimaciones, no informes auditados).

Desde 2.11.0, cada herramienta también declara un outputSchema tipado y devuelve structuredContent — el sobre de respuesta v1 de FreightUtils: la respuesta bajo result, más confidence, normalized_input, warnings, _source y un citation listo para usar. El canal de texto JSON plano heredado no cambia (byte-idéntico), por lo que los consumidores existentes de análisis de texto no se ven afectados.

Sitio web: https://www.freightutils.com Documentación de API: https://www.freightutils.com/api-docs

Herramientas (25)

Calculadoras

Herramienta	Descripción
`ldm_calculator`	Metros de carga para remolques de carretera europeos y estadounidenses
`cbm_calculator`	Metros cúbicos para flete marítimo
`chargeable_weight_calculator`	Peso facturable de flete aéreo (volumétrico vs. real)
`pallet_fitting_calculator`	Optimización de caja sobre palé con rotación
`container_lookup`	Especificaciones de contenedores ISO (10 tipos) y cálculo de carga
`unit_converter`	Conversiones de peso, volumen, longitud y específicas de flete
`consignment_calculator`	CBM, LDM, peso volumétrico y peso facturable específico por modo (marítimo/aéreo/carretera) para múltiples artículos + indicadores de asesoramiento
`emissions_calculator`	CO2e de flete mediante el método basado en distancia ISO 14083 / GLEC — factores abiertos DEFRA/EPA/ADEME (WTW + TTW); usar masa bruta real (no facturable/volumétrica); el resultado incluye empty_running + representatividad (marítimo/aéreo = baja) + un resumen

Mercancías Peligrosas (ADR)

Herramienta	Descripción
`adr_lookup`	2.939 entradas UNECE ADR 2025
`adr_exemption_calculator`	Verificación de exención de carga pequeña ADR 1.1.3.6
`adr_lq_eq_check`	Elegibilidad de Cantidad Limitada y Exceptuada

Algunos números ONU tienen más de una fila en la Tabla A del ADR (grupos de embalaje, bandas de concentración). Cuando un número ONU simple coincide con filas que dan respuestas diferentes, las herramientas ADR nunca eligen una: retienen el veredicto y devuelven las filas candidatas, y usted fija una con packing_group o variant_index. Las reglas, con casos resueltos (UN 1789, UN 1790 PG I, UN 2215 PG III): la calculadora ADR 1.1.3.6 en la documentación de API.

Aduanas y Aranceles

Herramienta	Descripción
`hs_code_lookup`	6.940 códigos arancelarios del Sistema Armonizado (HS 2022)
`uk_duty_calculator`	Derechos de importación e IVA del Reino Unido (datos en vivo del Arancel de Comercio GOV.UK)
`incoterms_lookup`	Incoterms 2020 — las 11 reglas con puntos de transferencia de riesgo y costo
`ics2_check`	Marcar términos de descripción de mercancías inaceptables de ICS2 de la UE (palabras vacías) antes de presentar un ENS — solo referencia

Datos de Referencia

Herramienta	Descripción
`resolve_reference`	Resolver cualquier identificador de flete ("176", "UN1845", "NLRTM", "FOB") a candidatos tipados, clasificados y citados cuando su tipo es desconocido
`airline_lookup`	6.356 aerolíneas con códigos IATA/ICAO y prefijos AWB
`unlocode_lookup`	Más de 116.232 ubicaciones de transporte UN/LOCODE
`airport_lookup`	85.555 aeropuertos por código IATA/ICAO, nombre o ciudad (OurAirports)
`nearest_airport`	Aeropuertos más cercanos a una latitud/longitud, por distancia de círculo máximo
`uld_lookup`	16 tipos de ULD de carga aérea (LD3, PMC, etc.)
`vehicle_lookup`	17 vehículos y remolques de flete por carretera

Validación

Herramienta	Descripción
`validate`	Analizar cualquier texto (una línea de reserva, un correo electrónico) para encontrar y validar cada contenedor (ISO 6346), AWB (módulo-7) y número IMO en él — o validar un identificador único por tipo

Compuesta

Herramienta	Descripción
`shipment_summary`	Encadena CBM + peso + LDM + ADR + aranceles en una sola llamada

Planes

Herramienta	Descripción
`get_subscribe_link`	La URL de la página de precios con el límite y precio del plan Pro (50.000/mes a £19/mes)

Instalación

Claude (claude.ai, aplicaciones de escritorio y móviles, Cowork)

Agregue FreightUtils desde el directorio de conectores de Claude: https://claude.ai/directory/connectors/freightutils. O agréguelo como conector personalizado — Personalizar → Conectores → Agregar conector personalizado — con la URL https://www.freightutils.com/api/mcp. Sin clave de API, sin inicio de sesión. Configuración, límites y privacidad: freightutils.com/mcp#use-in-claude.

Claude Desktop / Claude Code (stdio)

Agregue a su configuración de MCP (claude_desktop_config.json o .claude/settings.json):

{
  "mcpServers": {
    "freightutils": {
      "command": "npx",
      "args": ["freightutils-mcp"]
    }
  }
}

HTTP / SSE remoto

Si su cliente MCP admite servidores remotos, use la URL canónica:

https://www.freightutils.com/api/mcp

La URL más antigua https://www.freightutils.com/api/mcp/mcp sigue funcionando por compatibilidad con clientes existentes.

No se requiere clave de API para comenzar: las llamadas anónimas funcionan de inmediato (consulte Límites de velocidad a continuación).

Autenticación con una clave Pro

El uso anónimo tiene un límite de 25 solicitudes/día por IP. Si tiene una clave de API gratuita o Pro, configure FREIGHTUTILS_API_KEY en el entorno que ejecuta el servidor MCP. El paquete la lee de process.env y adjunta Authorization: Bearer <key> a cada llamada saliente de /api/* — la misma clave que el transporte remoto https://www.freightutils.com/api/mcp ya reconoce.

Ejemplo de configuración stdio con la variable de entorno conectada:

{
  "mcpServers": {
    "freightutils": {
      "command": "npx",
      "args": ["freightutils-mcp"],
      "env": {
        "FREIGHTUTILS_API_KEY": "fu_pk_xxx"
      }
    }
  }
}

Obtenga una clave en freightutils.com/api-docs (gratuita, 100/día) o freightutils.com/pricing (Pro, 50.000/mes). Compatible con versiones anteriores: la variable de entorno sin configurar conserva el comportamiento anónimo existente.

Sin clave configurada, el servidor lo indica una vez al inicio, en stderr (stdout lleva solo el protocolo MCP), para que una clave que pretendía configurar y no configuró aparezca en el registro MCP de su cliente en lugar de en el primer 429:

freightutils-mcp: FREIGHTUTILS_API_KEY is not set, so calls use the anonymous tier — 25 requests per day per IP address. Set the key to use your plan's limit: https://www.freightutils.com/pricing

Verifique su configuración

Después de agregar FreightUtils a la configuración de su cliente MCP, cierre y reinicie completamente el cliente (Claude Desktop, Cursor, Cline). Los servidores MCP solo se cargan al iniciar el cliente; editar la configuración en una sesión en ejecución no hace nada hasta reiniciar.

Luego ejecute el diagnóstico de instalación desde una terminal:

npx freightutils-mcp ping

Debería ver tres marcas de verificación y All checks passed:

FreightUtils MCP Diagnostic
───────────────────────────
package: freightutils-mcp@<installed version>
health:  https://www.freightutils.com/api/mcp/health

[1/3] Backend health (https://www.freightutils.com/api/mcp/health)
      ✓ status=ok mcp_version=<current> tools_registered=<current> (143ms)

[2/3] MCP handshake (in-process via InMemoryTransport)
      ✓ server freightutils-mcp@<installed version> initialized; tools/list returned <n> tools

[3/3] End-to-end tool call (cbm_calculator l=120 w=80 h=100)
      ✓ cbm_calculator → total=0.96 m³ (expected 0.96) (218ms)

All checks passed. Your FreightUtils MCP install is working.

Si alguna verificación muestra ✗, consulte Solución de problemas a continuación. El código de salida es 0 si todo pasa y 1 ante cualquier fallo, por lo que el comando también funciona en scripts de CI / verificación de salud.

Solución de problemas

Síntoma	Causa probable	Solución
Las herramientas no aparecen en el cliente MCP después de editar la configuración	El cliente no se reinició por completo	Cierre y reinicie (Cmd+Q en macOS / clic derecho → Salir en la bandeja de Windows). Cerrar la ventana no es suficiente.
La verificación 1 de `npx freightutils-mcp ping` falla con un error de red	DNS, proxy o el sitio web no es accesible desde su red	Consulte la página de estado en https://www.freightutils.com/status.. Si está detrás de un proxy corporativo, configure `HTTPS_PROXY`. Anule el host para `ping` con `FREIGHTUTILS_API_URL=<base-url>`.
La verificación 2 de `npx freightutils-mcp ping` falla	Instalación local dañada (caché de npx o versión de Node desactualizada)	Reinstale: `rm -rf ~/.npm/_npx && npm install -g freightutils-mcp` y vuelva a ejecutar. Requiere Node 18 o superior.
Las llamadas a herramientas devuelven HTTP 429 / `"rate_limited"`	Se excedió el límite anónimo de 25 solicitudes/día por IP	Si tiene una clave de API Pro de FreightUtils, configure `FREIGHTUTILS_API_KEY` en su entorno antes de invocar el MCP. El paquete la transmite automáticamente en cada llamada saliente. Consulte https://www.freightutils.com/pricing si necesita una clave.
`"Server failed to start"` / error de spawn en los registros del cliente	`npx` no está en PATH, o Node es anterior a 18	Instale Node 18+. En macOS, una ruta absoluta en la configuración (`"command": "/opt/homebrew/bin/npx"`) evita problemas de PATH para clientes iniciados por GUI.
Una herramienta específica devuelve `isError: true`	Forma de entrada incorrecta, o una clave de búsqueda desconocida (número ONU / código HS / prefijo AWB no en el conjunto de datos)	El cuerpo del error de la herramienta nombra el campo problemático. Verifique contra el esquema en https://www.freightutils.com/api-docs o llame al endpoint de playground correspondiente para confirmar la forma de entrada.

El flujo de diagnóstico completo está en la sección /api-docs#mcp-setup del sitio web. El estado del backend en vivo se puede consultar desde cualquier cliente MCP en GET /api/mcp/health — útil cuando no tiene acceso a shell durante una conversación.

Límites de velocidad

Todas las herramientas llaman a la API gratuita de FreightUtils:

Anónimo: 25 solicitudes/día por IP
Clave de API gratuita: 100 solicitudes/día (regístrese en https://www.freightutils.com)
Pro: 50.000 solicitudes/mes a £19/mes

Seguridad y datos

Solo lectura. Cada herramienta es una consulta o un cálculo, declarado readOnlyHint: true y destructiveHint: false. El servidor no cambia nada, en ningún lugar.
Sin sistema de archivos, sin shell. El servidor no lee ningún archivo excepto su propio package.json, no inicia ningún proceso y no abre ningún puerto — se comunica solo por stdio.
Un destino. Las entradas de las herramientas van solo a https://www.freightutils.com/api (o la base que configure en FREIGHTUTILS_API_URL), a través de HTTPS. get_subscribe_link responde localmente y no envía nada.
La clave permanece en el entorno. FREIGHTUTILS_API_KEY se lee del entorno y se envía solo como encabezado Authorization: Bearer a ese host — nunca se registra, nunca se escribe en disco, nunca se incluye en un mensaje de error.
stdout es el protocolo. Nada más que MCP JSON-RPC va a stdout; el único aviso de inicio va a stderr.
Dos capas de validación. El esquema Zod de cada herramienta verifica tipos, formatos y los propios límites de la API antes de realizar cualquier llamada (las tres herramientas ADR — adr_exemption_calculator, adr_lq_eq_check, shipment_summary — también rechazan, por nombre, un campo que no leen). La API luego valida cada solicitud nuevamente en el servidor y rechaza lo que no puede responder con un 400 que nombra el campo.
Los errores conservan su significado. Una llamada fallida se informa por tipo: fallo de red, tiempo de espera (30 s, o FREIGHTUTILS_TIMEOUT_MS), rechazo 4xx de la propia API, un 429 con su reset_at, o un 5xx — nunca con un seguimiento de pila, un encabezado de solicitud o el contenido de una página de error del servidor.
Dos dependencias de ejecución directas: @modelcontextprotocol/sdk y zod. CI falla ante cualquier aviso alto o crítico en el árbol de dependencias de producción, y Dependabot lo supervisa.
Informar una vulnerabilidad: consulte SECURITY.md.

Ejemplos de indicaciones

Una vez conectado, su agente de IA puede:

"Calcular CBM para una caja de 120 cm × 80 cm × 100 cm, 24 piezas"
"Buscar UN 1203 en la base de datos ADR"
"Verificar si 200 L de gasolina califican para la exención ADR 1.1.3.6"
"Encontrar el código HS para baterías de litio"
"¿Qué significa FOB en el transporte marítimo?"
"¿Cuántas cajas de 40×30×25 cm caben en un palé europeo?"
"Calcular metros de carga para 26 palés europeos en un remolque articulado"
"¿Cuál es el arancel de importación del Reino Unido para portátiles desde China?"

Fuentes de datos

ADR 2025 — UNECE, ECE/TRANS/352, aplicable desde el 1 de enero de 2025; con efecto legal mediante la Directiva 2008/68/CE de la UE (consolidada). Compilación factual, con el mejor esfuerzo posible — no constituye asesoramiento legal ni autoridad regulatoria.
HS 2022 — Descripciones HS 2022 de la clasificación H6 de UN Comtrade (División de Estadística de la ONU); la OMA mantiene la nomenclatura del Sistema Armonizado. Sin licencia abierta nombrada.
Aerolíneas — Compilado por FreightUtils a partir de fuentes públicas. Los registros verificados citan páginas publicadas por las aerolíneas y la Orden FAA JO 7340.2 campo por campo; el resto está pendiente de verificación. IATA e ICAO asignan estos códigos, pero este conjunto de datos no está publicado ni respaldado por IATA o ICAO, y no se hace ninguna reclamación de licencia o "datos abiertos" para el mismo.
UN/LOCODE 2025-1 — Artefacto de publicación oficial de UNECE, coordenadas estrictamente validadas. UN/LOCODE © UNECE, CC BY 4.0 (como UNECE declara para los estándares UN/CEFACT).
Arancel del Reino Unido — La API en vivo del Arancel Comercial GOV.UK, consultada por solicitud, por lo que no hay una copia local que pueda desactualizarse.
Contenedores / ULD / vehículos — Especificaciones estándar de ISO, IATA y de la industria.
Factores de emisiones — Factores publicados por DEFRA / EPA / ADEME (actualmente DEFRA 2026 + EPA 2025 + ADEME Base Carbone v23.11), combinados mediante el método basado en distancia ISO 14083 / GLEC. Estimaciones, no informes auditados.

La redacción pública de procedencia se mantiene en el repositorio de FreightUtils en docs/DATA_PROVENANCE.md y se copia aquí, no escrita de memoria — por lo que una fuente que se re-atribuya allí no puede seguir citándose aquí.

Historial de cambios

Notas de versión: CHANGELOG.md en este repositorio y GitHub Releases.

Un README que lleva su propia copia del historial de cambios es la razón por la que tres directorios mostraron 2.4.0 como la última versión durante tres meses después de que 2.4.0 hubiera sido superada. Una sola fuente ahora.

Otras formas de usar FreightUtils

FreightUtils se distribuye a través de múltiples superficies de distribución. Elige la que se adapte a tu forma de trabajar:

Sitio web — Herramientas interactivas en freightutils.com
API REST — 24 endpoints, nivel gratuito (100/día) y nivel Pro (50K/mes, £19/mes). Documentación de la API
Servidor MCP — Para agentes LLM y herramientas de IA. npm: freightutils-mcp · Registro MCP
Nodo personalizado n8n — Para automatización de flujos de trabajo. npm: n8n-nodes-freightutils
GPT personalizado — El FreightUtils GPT en la tienda de GPT de OpenAI, respaldado por la misma especificación OpenAPI.

Mismos datos, mismo conjunto de referencia de cumplimiento (ADR 2025, HS 2022, prefijos de aerolíneas regulados por IATA), cada superficie mantenida sincronizada.

Licencia

MIT — ver LICENSE.

Construido por Marius Cristoiu, planificador de transporte de mercancías certificado ADR.