mcp-comex-brasil

Servidor MCP de comercio exterior de Brasil — con las trampas del dataset corregidas en la respuesta.

Cuatro herramientas que no mienten, en lugar de cuarenta que no saben.

El problema que resuelve este servidor

Un servidor MCP que solo expone un dataset entrega al agente una API limpia para un número equivocado. La fontanería no sabe que el campo miente.

El Comex Stat — la base oficial de comercio exterior de Brasil, publicada por la Secretaria de Comércio Exterior / Receita Federal — tiene un defecto que ninguna documentación advierte:

Filtrar el campo de modal por AÉREA devuelve 139,6 millones de kg de importación de China en 2026 (ene–jul). Cruzando esos mismos registros con el punto de despacho, solo 34,0 millones (24%) pasaron por un aeropuerto. Los otros 89,7 millones se despacharon en puertos marítimos y son sulfato de amonio y fertilizantes fosfáticos — carga que no vuela, a US$0,29/kg de flete.

Sin corregir: peso aéreo 4,1× inflado y flete por kilo 70% subestimado. El error es silencioso: nada en la consulta lo acusa.

Este servidor aplica la corrección y devuelve junto con la evidencia de por qué es necesaria.

Related MCP server: mcp-comtrade

Las dos garantías

1. Toda respuesta incluye los defectos conocidos que se aplican a esa consulta, con evidencia medida y procedencia de la verificación.

2. La corrección crítica está aplicada en el resultado, no solo avisada. El canal air ya significa "aéreo despachado en aeropuerto". El bloque contaminado sigue consultable como air_declared_at_port, a propósito — para quien quiera inspeccionarlo.

Lo que el dataset tiene y que los resúmenes publicados desechan

Los archivos de importación contienen VL_FRETE y VL_SEGURO — flete y seguro declarados en la aduana. Es la mejor medida sistemática de coste incurrido disponible públicamente, y prácticamente nadie la usa.

China → Brasil, ene–jul de 2026, ya corregido:

El aéreo cuesta 76× más por kilo y solo 1,65× más por dólar de mercancía. El reparto modal de este corredor no es una decisión de flete — es una decisión de densidad de valor.

Instalación

Requiere Node ≥ 22.5 (usa el SQLite integrado — cero dependencias 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

El db:build obtiene los archivos directamente de balanca.economia.gov.br. Ningún dato es redistribuido por este paquete — la base se construye en tu máquina, siempre fresca de la fuente.

Opciones útiles:

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

Configuración en el cliente MCP

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

COMEX_LANG acepta pt (por defecto) o en. COMEX_DB sobrescribe la ruta de la base de datos.

Las cuatro herramientas

Las advertencias que acompañan las respuestas

Sobre simplified_regime_absent: existen códigos de modal para POSTAL y COURIER, pero están vacíos (13 registros y 72 kg para China en todo 2026, frente a ~180 millones de envíos internacionales reportados). Las remesas de bajo valor pasan por el régimen simplificado y no entran en las estadísticas de comercio. La estadística formal y el volumen de envíos son universos disjuntos — no sumar, no comparar aritméticamente.

Verificación

Los agregados fueron validados mediante implementación cruzada: el mismo corte procesado con una pasada de awk sobre el CSV crudo y con la vista SQL de este servidor produce números idénticos hasta el último dígito (349.250 registros, 7 canales, valores de flete y peso).

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

Licencia y fuente

MIT. Datos: Comex Stat, Secretaria de Comércio Exterior / Receita Federal de Brasil (balanca.economia.gov.br) — fuente pública, consultada durante la construcción de la 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