mcp-comex-brasil

Servidor MCP de comércio exterior do Brasil — com as armadilhas do dataset corrigidas na resposta.

Quatro tools que não mentem, em vez de quarenta que não sabem.

O problema que este servidor resolve

Um servidor MCP que apenas expõe um dataset entrega ao agente uma API limpa para um número errado. A encanação não sabe que o campo mente.

O Comex Stat — a base oficial de comércio exterior do Brasil, publicada pela Secretaria de Comércio Exterior / Receita Federal — tem um defeito que nenhuma documentação avisa:

Filtrar o campo de modal por AÉREA retorna 139,6 milhões de kg de importação da China em 2026 (jan–jul). Cruzando esses mesmos registros com o ponto de despacho, apenas 34,0 milhões (24%) passaram por um aeroporto. Os outros 89,7 milhões despacharam em portos marítimos e são sulfato de amônio e fertilizantes fosfáticos — carga que não voa, a US$0,29/kg de frete.

Sem corrigir: peso aéreo 4,1× inflado e frete por quilo 70% subestimado. O erro é silencioso: nada na consulta acusa.

Este servidor aplica a correção, e devolve junto a evidência de por que ela é necessária.

Related MCP server: mcp-comtrade

As duas garantias

1. Toda resposta traz os defeitos conhecidos que se aplicam àquela consulta, com evidência medida e procedência da verificação.

2. A correção crítica está aplicada no resultado, não apenas avisada. O canal air já significa "aéreo despachado em aeroporto". O bloco contaminado continua consultável como air_declared_at_port, de propósito — para quem quiser inspecionar.

O que o dataset tem que os resumos publicados jogam fora

Os arquivos de importação carregam VL_FRETE e VL_SEGURO — frete e seguro declarados à aduana. É a melhor medida sistemática de custo realizado disponível publicamente, e praticamente ninguém a usa.

China → Brasil, jan–jul de 2026, já corrigido:

O aéreo custa 76× mais por quilo e apenas 1,65× mais por dólar de mercadoria. O split modal deste corredor não é uma decisão de frete — é uma decisão de densidade de valor.

Instalação

Requer Node ≥ 22.5 (usa o SQLite embutido — zero dependências nativas, nada de node-gyp).

git clone <repo> && cd mcp-comex-brasil
npm install && npm run build
npm run db:build -- --years 2025,2026        # baixa da fonte oficial e monta o SQLite

O db:build busca os arquivos direto de balanca.economia.gov.br. Nenhum dado é redistribuído por este pacote — a base é construída na sua máquina, sempre fresca da fonte.

Opções úteis:

npm run db:build -- --years 2026 --countries 160        # só China, base pequena e rápida
npm run db:build -- --years 2024,2025,2026 --flows import,export

Configuração no cliente MCP

{
  "mcpServers": {
    "comex": {
      "command": "node",
      "args": ["--experimental-sqlite", "/caminho/para/mcp-comex-brasil/dist/index.js"],
      "env": { "COMEX_LANG": "pt" }
    }
  }
}

COMEX_LANG aceita pt (default) ou en. COMEX_DB sobrescreve o caminho do banco.

As quatro tools

Os caveats que acompanham as respostas

Sobre simplified_regime_absent: existem códigos de modal para POSTAL e COURIER, mas estão vazios (13 registros e 72 kg para a China em todo 2026, contra ~180 milhões de encomendas internacionais reportadas). As remessas de baixo valor passam pelo regime simplificado e não entram nas estatísticas de comércio. Estatística formal e volume de encomenda são universos disjuntos — não somar, não comparar aritmeticamente.

Verificação

Os agregados foram validados por implementação cruzada: o mesmo recorte processado por uma passada de awk sobre o CSV cru e pela view SQL deste servidor produz números idênticos até o último dígito (349.250 registros, 7 canais, valores de frete e peso).

npm test     # 12 testes da lógica de classificação e do registro de caveats

Licença e fonte

MIT. Dados: Comex Stat, Secretaria de Comércio Exterior / Receita Federal do Brasil (balanca.economia.gov.br) — fonte pública, consultada em tempo de construção da base.

Autor: Luis Delfin

English

MCP server for Brazilian foreign-trade data — with the dataset's traps corrected in the response.

Four tools that don't lie, instead of forty that don't know.

The problem

An MCP server that merely exposes a dataset hands the agent a clean API to a wrong number. The plumbing doesn't know the field lies.

Brazil's official trade dataset (Comex Stat, published by the Foreign Trade Secretariat / Federal Revenue Service) has a defect no documentation warns about:

Filtering the transport-mode field by AIR returns 139.6 million kg of Chinese imports for Jan–Jul 2026. Cross-referencing those same records against their clearance point, only 34.0 million (24%) passed through an airport. The other 89.7 million cleared at seaports and consist of ammonium sulphate and phosphatic fertilisers — cargo that does not fly, at US$0.29/kg freight.

Uncorrected: air weight overstated 4.1× and freight per kg understated by 70%. The error is silent — nothing in the query flags it.

This server applies the correction, and returns the evidence for why it is needed.

Two guarantees

1. Every response carries the known defects that apply to that query, with measured evidence and verification provenance.

2. The critical correction is applied, not merely warned about. The air channel already means "air mode cleared at an airport". The contaminated block stays queryable as air_declared_at_port, deliberately — for anyone who wants to inspect it.

What the dataset has that published summaries discard

The import files carry VL_FRETE and VL_SEGURO — freight and insurance as declared to customs. It is the best systematic measure of realised cost available publicly, and almost nobody uses it.

China → Brazil, Jan–Jul 2026, corrected:

Air costs 76× more per kilogram and only 1.65× more per dollar of goods. This corridor's modal split is not a freight decision — it is a value-density decision.

Install

Requires Node ≥ 22.5 (uses built-in SQLite — zero native dependencies, no node-gyp).

npm install && npm run build
npm run db:build -- --years 2025,2026        # fetches from the official source, builds SQLite

db:build pulls the files straight from balanca.economia.gov.br. No data is redistributed by this package — the database is built on your machine, always fresh from the source.

The four tools

Verification

Aggregates were validated by cross-implementation: the same slice processed by a single awk pass over the raw CSV and by this server's SQL view produces identical figures to the last digit (349,250 records, 7 channels, freight and weight values).

npm test     # 12 tests covering the classification logic and the caveat registry

MIT. Data: Comex Stat, Brazilian Foreign Trade Secretariat / Federal Revenue Service. Author: Luis Delfin