FreightUtils MCP Server

Servidor MCP FreightUtils

A camada de referência neutra de frete para agentes de IA.

FreightUtils é a camada de referência neutra de frete para agentes de IA — dados de mercadorias perigosas, alfândega, localização e cálculo de frete com origem em fontes primárias (ADR 2025 / UNECE, HS 2022 / OMC, prefixos de companhias aéreas regulados pela IATA), que um agente pode consultar e citar. Neutro por design: não há frete a vender nem transportadora a promover — uma consulta retorna o que a fonte nomeada diz, com a citação anexada para que um agente possa inspecioná-la em vez de aceitar nossa palavra, independentemente de quem transporta a carga.

Este servidor Model Context Protocol dá aos agentes de IA acesso a 25 ferramentas de cálculo e referência de frete, cobrindo frete rodoviário, aéreo e marítimo. Construído por um planejador de transporte de frete certificado ADR no Reino Unido.

Toda resposta cita sua fonte — um bloco _source com a autoridade, edição, licença quando aplicável e um status de verificação que um agente pode ler — e as ferramentas são determinísticas, não respostas geradas. Apenas referência: nunca arquivamento, reserva ou aconselhamento jurídico, e os resultados indicam quando é necessária revisão humana (validate é apenas validação estrutural de dígito verificador; um ics2_check limpo não é aceitação ENS; os valores de emissões são estimativas, não relatórios auditados).

Desde a 2.11.0, toda ferramenta também declara um outputSchema tipado e retorna structuredContent — o envelope de resposta FreightUtils v1: a resposta em result, além de confidence, normalized_input, warnings, _source e um citation pronto para uso. O canal legado de texto JSON simples permanece inalterado (byte-idêntico), portanto os consumidores existentes de análise de texto não são afetados.

Site: https://www.freightutils.com Documentação da API: https://www.freightutils.com/api-docs

---

Ferramentas (25)

Calculadoras

Ferramenta	Descrição
ldm_calculator	Metros de carga para reboques rodoviários europeus e dos EUA
cbm_calculator	Metros cúbicos para frete marítimo
chargeable_weight_calculator	Peso tributável de frete aéreo (volumétrico vs. real)
pallet_fitting_calculator	Otimização de caixa sobre palete com rotação
container_lookup	Especificações de contêiner ISO (10 tipos) e cálculo de carga
unit_converter	Conversões de peso, volume, comprimento e específicas de frete
consignment_calculator	CBM multi-item, LDM, volumétrico e peso tributável específico por modal (marítimo/aéreo/rodoviário) + sinalizadores de aviso
emissions_calculator	CO2e de frete pelo método baseado em distância ISO 14083 / GLEC — fatores abertos DEFRA/EPA/ADEME (WTW + TTW); use massa bruta real (não tributável/volumétrica); o resultado inclui empty_running + representatividade (marítimo/aéreo = baixa) + um resumo

Mercadorias Perigosas (ADR)

Ferramenta	Descrição
adr_lookup	2.939 entradas UNECE ADR 2025
adr_exemption_calculator	Verificação de isenção de pequena carga ADR 1.1.3.6
adr_lq_eq_check	Elegibilidade para Quantidade Limitada e Isenta

Alguns números ONU têm mais de uma linha na Tabela A do ADR (grupos de embalagem, faixas de concentração). Quando um número ONU simples corresponde a linhas que dão respostas diferentes, as ferramentas ADR nunca escolhem uma: elas retêm o veredito e retornam as linhas candidatas, e você fixa uma com packing_group ou variant_index. As regras, com casos trabalhados (UN 1789, UN 1790 PG I, UN 2215 PG III): a calculadora ADR 1.1.3.6 na documentação da API.

Alfândega e Tarifas

Ferramenta	Descrição
hs_code_lookup	6.940 códigos tarifários do Sistema Harmonizado (HS 2022)
uk_duty_calculator	Imposto de importação e IVA do Reino Unido (dados ao vivo da Tarifa Comercial GOV.UK)
incoterms_lookup	Incoterms 2020 — todas as 11 regras com pontos de transferência de risco/custo
ics2_check	Sinalizar termos de descrição de mercadorias inaceitáveis do ICS2 da UE (palavras de parada) antes de arquivar um ENS — apenas referência

Dados de Referência

Ferramenta	Descrição
resolve_reference	Resolver qualquer identificador de frete ("176", "UN1845", "NLRTM", "FOB") para candidatos tipados, classificados e citados quando o tipo é desconhecido
airline_lookup	6.356 companhias aéreas com códigos IATA/ICAO e prefixos AWB
unlocode_lookup	Mais de 116.232 locais de transporte UN/LOCODE
airport_lookup	85.555 aeroportos por código IATA/ICAO, nome ou cidade (OurAirports)
nearest_airport	Aeroportos mais próximos de uma latitude/longitude, por distância de grande círculo
uld_lookup	16 tipos de ULD de carga aérea (LD3, PMC, etc.)
vehicle_lookup	17 veículos e reboques de frete rodoviário

Validação

Ferramenta	Descrição
validate	Analisar qualquer texto (uma linha de reserva, um e-mail) para encontrar e validar todo contêiner (ISO 6346), AWB (módulo-7) e número IMO nele — ou validar um único identificador por tipo

Composta

Ferramenta	Descrição
shipment_summary	Encadeia CBM + peso + LDM + ADR + imposto em uma única chamada

Planos

Ferramenta	Descrição
get_subscribe_link	A URL da página de preços com o limite e preço do plano Pro (50.000/mês a £19/mês)

---

Instalação

Claude (claude.ai, aplicativos desktop e móveis, Cowork)

Adicione FreightUtils pelo diretório de conectores do Claude: https://claude.ai/directory/connectors/freightutils. Ou adicione como conector personalizado — Personalizar → Conectores → Adicionar conector personalizado — com a URL https://www.freightutils.com/api/mcp. Sem chave de API, sem login. Configuração, limites e privacidade: freightutils.com/mcp#use-in-claude.

Claude Desktop / Claude Code (stdio)

Adicione à sua configuração MCP (claude_desktop_config.json ou .claude/settings.json):

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

HTTP / SSE remoto

Se seu cliente MCP suporta servidores remotos, use a URL canônica:

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

A URL mais antiga https://www.freightutils.com/api/mcp/mcp ainda funciona para compatibilidade retroativa com clientes existentes.

Nenhuma chave de API é necessária para começar — chamadas anônimas funcionam imediatamente (veja Limites de Taxa abaixo).

Autenticando com uma chave Pro

O uso anônimo é limitado a 25 solicitações/dia por IP. Se você tiver uma chave de API gratuita ou Pro, defina FREIGHTUTILS_API_KEY no ambiente que executa o servidor MCP. O pacote a lê de process.env e anexa Authorization: Bearer <key> a toda chamada de saída /api/* — a mesma chave que o transporte remoto https://www.freightutils.com/api/mcp já honra.

Exemplo de configuração stdio com a variável de ambiente conectada:

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

Obtenha uma chave em freightutils.com/api-docs (gratuita, 100/dia) ou freightutils.com/pricing (Pro, 50.000/mês). Compatível retroativamente — variável de ambiente não definida preserva o comportamento anônimo existente.

Sem chave definida, o servidor informa isso uma vez na inicialização, em stderr (stdout carrega apenas o protocolo MCP), para que uma chave que você pretendia definir e esqueceu apareça no log MCP do seu cliente em vez de no primeiro 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 sua configuração

Após adicionar FreightUtils à configuração do seu cliente MCP, saia e reinicie completamente o cliente (Claude Desktop, Cursor, Cline). Os servidores MCP são carregados apenas na inicialização do cliente; editar a configuração em uma sessão em execução não faz nada até a reinicialização.

Em seguida, execute o diagnóstico de instalação a partir de um terminal:

npx freightutils-mcp ping

Você deve ver três marcas de verificação e 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.

Se alguma verificação mostrar ✗, veja Solução de Problemas abaixo. O código de saída é 0 em caso de sucesso total e 1 em qualquer falha, portanto o comando também funciona em scripts de CI / verificação de saúde.

---

Solução de Problemas

Sintoma	Causa provável	Correção
Ferramentas não aparecem no cliente MCP após editar a configuração	O cliente não foi totalmente reiniciado	Saia e reinicie (Cmd+Q no macOS / clique com o botão direito → Sair na bandeja do Windows). Fechar a janela não é suficiente.
npx freightutils-mcp ping verificação 1 falha com erro de rede	DNS, proxy ou o site está inacessível pela sua rede	Verifique a página de status em https://www.freightutils.com/status. Se você estiver atrás de um proxy corporativo, defina HTTPS_PROXY. Substitua o host para ping com FREIGHTUTILS_API_URL=<base-url>.
npx freightutils-mcp ping verificação 2 falha	Instalação local quebrada (cache npx ou versão desatualizada do Node)	Reinstale: rm -rf ~/.npm/_npx && npm install -g freightutils-mcp e execute novamente. Requer Node 18 ou mais recente.
Chamadas de ferramenta retornam HTTP 429 / "rate_limited"	Limite anônimo de IP de 25 solicitações/dia excedido	Se você tiver uma chave de API Pro FreightUtils, defina FREIGHTUTILS_API_KEY no seu ambiente antes de invocar o MCP. O pacote a repassa automaticamente em toda chamada de saída. Veja https://www.freightutils.com/pricing se precisar de uma chave.
"Server failed to start" / erro de spawn nos logs do cliente	npx não está no PATH, ou Node mais antigo que 18	Instale Node 18+. No macOS, um caminho absoluto na configuração ("command": "/opt/homebrew/bin/npx") evita problemas de PATH para clientes iniciados por GUI.
Ferramenta específica retorna isError: true	Formato de entrada ruim, ou chave de consulta desconhecida (número UN / código HS / prefixo AWB não no conjunto de dados)	O corpo do erro da ferramenta nomeia o campo problemático. Verifique o esquema em https://www.freightutils.com/api-docs ou chame o endpoint correspondente do playground para confirmar o formato da entrada.

O fluxo de diagnóstico completo está na seção /api-docs#mcp-setup do site. O status do backend ao vivo pode ser chamado de dentro de qualquer cliente MCP em GET /api/mcp/health — útil quando você não tem acesso ao shell durante uma conversa.

---

Limites de Taxa

Todas as ferramentas chamam a API FreightUtils gratuita:

• Anônimo: 25 solicitações/dia por IP
• Chave de API gratuita: 100 solicitações/dia (registre-se em https://www.freightutils.com)
• Pro: 50.000 solicitações/mês a £19/mês

---

Segurança e dados

• Somente leitura. Toda ferramenta é uma consulta ou cálculo, declarada readOnlyHint: true e destructiveHint: false. O servidor não altera nada, em lugar nenhum.
• Sem sistema de arquivos, sem shell. O servidor não lê nenhum arquivo exceto seu próprio package.json, não inicia nenhum processo e não abre nenhuma porta — ele fala apenas via stdio.
• Um único destino. As entradas das ferramentas vão apenas para https://www.freightutils.com/api (ou a base que você definir em FREIGHTUTILS_API_URL), via HTTPS. get_subscribe_link responde localmente e não envia nada.
• A chave permanece no ambiente. FREIGHTUTILS_API_KEY é lida do ambiente e enviada apenas como cabeçalho Authorization: Bearer para esse host — nunca registrada, nunca gravada em disco, nunca colocada em uma mensagem de erro.
• stdout é o protocolo. Nada além de MCP JSON-RPC vai para stdout; o único aviso de inicialização vai para stderr.
• Duas camadas de validação. O esquema Zod de cada ferramenta verifica tipos, formatos e os próprios limites da API antes de qualquer chamada ser feita (as três ferramentas ADR — adr_exemption_calculator, adr_lq_eq_check, shipment_summary — também recusam, pelo nome, um campo que não leem). A API então valida novamente toda solicitação no servidor e recusa o que não pode responder com um 400 nomeando o campo.
• Erros mantêm seu significado. Uma chamada falha é relatada por tipo: falha de rede, tempo limite (30 s, ou FREIGHTUTILS_TIMEOUT_MS), recusa 4xx da própria API, um 429 com seu reset_at, ou um 5xx — nunca com um rastreamento de pilha, cabeçalho de solicitação ou conteúdo de uma página de erro do servidor.
• Duas dependências diretas de tempo de execução: @modelcontextprotocol/sdk e zod. O CI falha em qualquer aviso alto ou crítico na árvore de dependências de produção, e o Dependabot a monitora.
• Relatando uma vulnerabilidade: veja SECURITY.md.

---

Exemplos de Prompts

Uma vez conectado, seu agente de IA pode:

• "Calcular CBM para uma caixa 120cm × 80cm × 100cm, 24 peças"
• "Consultar UN 1203 no banco de dados ADR"
• "Verificar se 200L de gasolina se qualifica para isenção ADR 1.1.3.6"
• "Encontrar o código HS para baterias de lítio"
• "O que significa FOB no transporte marítimo?"
• "Quantas caixas de 40×30×25cm cabem em um palete europeu?"
• "Calcular metros de carga para 26 paletes europeus em um reboque articulado"
• "Qual é o imposto de importação do Reino Unido sobre laptops da China?"

---

Fontes de Dados

• ADR 2025 — UNECE, ECE/TRANS/352, aplicável a partir de 1º de janeiro de 2025; com efeito legal conferido pela Diretiva 2008/68/EC da UE (consolidada). Compilação factual, com melhores esforços — não é aconselhamento jurídico, nem autoridade regulatória.
• HS 2022 — Descrições HS 2022 da classificação H6 da UN Comtrade (Divisão de Estatísticas da ONU); a WCO mantém a nomenclatura do Sistema Harmonizado. Sem licença aberta nomeada.
• Companhias aéreas — compilado pela FreightUtils a partir de fontes públicas. Registros verificados citam páginas publicadas pelas transportadoras e a Ordem FAA JO 7340.2 campo a campo; o restante está pendente de verificação. A IATA e a ICAO atribuem esses códigos, mas este conjunto de dados não é publicado ou endossado pela IATA ou ICAO, e nenhuma licença ou alegação de "dados abertos" é feita para ele.
• UN/LOCODE 2025-1 — artefato de lançamento oficial da UNECE, coordenadas estritamente validadas. UN/LOCODE © UNECE, CC BY 4.0 (conforme declarado pela UNECE para padrões UN/CEFACT).
• Imposto do Reino Unido — a API ao vivo do GOV.UK Trade Tariff, consultada por solicitação, portanto não há cópia local que possa ficar desatualizada.
• Contêineres / ULD / veículos — especificações ISO, IATA e padrões da indústria.
• Fatores de emissões — fatores publicados DEFRA / EPA / ADEME (atualmente DEFRA 2026 + EPA 2025 + ADEME Base Carbone v23.11), combinados pelo método baseado em distância ISO 14083 / GLEC. Estimativas, não relatórios auditados.

A redação pública de proveniência é mantida no repositório da FreightUtils em docs/DATA_PROVENANCE.md e copiada aqui, não escrita de memória — para que uma fonte que seja reatribuída lá não possa continuar sendo citada aqui.

---

Changelog

Notas de versão: CHANGELOG.md neste repositório e GitHub Releases.

Um README que carrega sua própria cópia do changelog é o motivo pelo qual três diretórios mostraram 2.4.0 como a versão mais recente por três meses após 2.4.0 ter sido substituída. Uma única fonte agora.

---

Outras formas de usar o FreightUtils

O FreightUtils está disponível em várias superfícies de distribuição. Escolha a que melhor se adapta ao seu fluxo de trabalho:

• Site — ferramentas interativas em freightutils.com
• API REST — 24 endpoints, plano gratuito (100/dia) e plano Pro (50K/mês, £19/mês). Documentação da API
• Servidor MCP — para agentes LLM e ferramentas de IA. npm: freightutils-mcp · MCP Registry
• Nó personalizado n8n — para automação de fluxos de trabalho. npm: n8n-nodes-freightutils
• GPT personalizado — o FreightUtils GPT na OpenAI GPT Store, apoiado pela mesma especificação OpenAPI.

Mesmos dados, mesmo conjunto de referência de conformidade (ADR 2025, HS 2022, prefixos de companhias aéreas regulamentados pela IATA), todas as superfícies mantidas em sincronia.

---

Licença

MIT — veja LICENSE.

Construído por Marius Cristoiu, planejador de transporte de carga certificado ADR.