mcp-comex-brasil

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 this server solves

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.

Comex Stat — the official Brazilian foreign-trade database, published by the Foreign Trade Secretariat / Federal Revenue Service — has a defect that no documentation warns about:

Filtering the transport-mode field by AÉREA returns 139.6 million kg of Chinese imports in 2026 (Jan–Jul). Cross-referencing these same records with the clearance point, only 34.0 million (24%) passed through an airport. The other 89.7 million cleared at seaports and are ammonium sulfate and phosphatic fertilizers — 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.

Related MCP server: Receita Federal: Radar (Habilitação Comércio Exterior)

The 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 to the result, not merely warned about. The air channel already means "air mode cleared at an airport". The contaminated block remains 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 realized cost available publicly, and almost nobody uses it.

China → Brazil, Jan–Jul 2026, already 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 the built-in SQLite — zero native dependencies, no 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

db:build fetches 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.

Useful options:

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

Configuring the MCP client

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

COMEX_LANG accepts pt (default) or en. COMEX_DB overrides the database path.

The four tools

The caveats that accompany the responses

About simplified_regime_absent: there are transport-mode codes for POSTAL and COURIER, but they are empty (13 records and 72 kg for China in all of 2026, versus ~180 million international parcels reported). Low-value shipments go through the simplified regime and do not enter trade statistics. Formal statistics and parcel volume are disjoint universes — do not add, do not compare arithmetically.

Verification

The 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 testes da lógica de classificação e do registro de caveats

License and source

MIT. Data: Comex Stat, Foreign Trade Secretariat / Federal Revenue Service of Brazil (balanca.economia.gov.br) — public source, consulted at database build time.

Author: 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