mcp-comex-brasil

MCP-Server für brasilianische Außenhandelsdaten — mit den in der Antwort korrigierten Fallstricken des Datensatzes.

Vier Tools, die nicht lügen, statt vierzig, die nichts wissen.

Das Problem, das dieser Server löst

Ein MCP-Server, der einen Datensatz nur exponiert, übergibt dem Agenten eine saubere API für eine falsche Zahl. Die Infrastruktur weiß nicht, dass das Feld lügt.

Comex Stat — die offizielle Außenhandelsdatenbank Brasiliens, veröffentlicht von der Secretaria de Comércio Exterior / Receita Federal — hat einen Defekt, vor dem keine Dokumentation warnt:

Filtert man das Transportmodus-Feld nach AÉREA, erhält man 139,6 Mio. kg Importe aus China im Jahr 2026 (Jan–Jul). Kreuzt man dieselben Datensätze mit dem Verzollungspunkt, haben nur 34,0 Mio. (24 %) einen Flughafen passiert. Die übrigen 89,7 Mio. wurden in Seehäfen verzollt und bestehen aus Ammoniumsulfat und Phosphatdünger — Fracht, die nicht fliegt, zu 0,29 US$/kg Fracht.

Ohne Korrektur: Luftgewicht 4,1× aufgebläht und Fracht pro Kilo um 70 % unterbewertet. Der Fehler ist still: Nichts in der Abfrage weist darauf hin.

Dieser Server wendet die Korrektur an und liefert zugleich die Belege dafür, warum sie nötig ist.

Related MCP server: mcp-comtrade

Die zwei Garantien

1. Jede Antwort enthält die bekannten Fehler, die für diese Abfrage gelten, mit gemessenen Belegen und Herkunft der Überprüfung.

2. Die kritische Korrektur ist im Ergebnis angewendet, nicht nur angekündigt. Der Kanal air bedeutet bereits „auf dem Flughafen abgefertigte Luftfracht“. Der kontaminierte Block bleibt absichtlich als air_declared_at_port abfragbar — für alle, die ihn prüfen möchten.

Was der Datensatz enthält, das veröffentlichte Zusammenfassungen verwerfen

Die Importdateien enthalten VL_FRETE und VL_SEGURO — Fracht und Versicherung, wie beim Zoll angegeben. Es ist das beste öffentlich verfügbare systematische Maß für realisierte Kosten, und praktisch niemand nutzt es.

China → Brasilien, Jan–Jul 2026, bereits korrigiert:

Luftfracht kostet 76× mehr pro Kilo und nur 1,65× mehr pro Dollar Warenwert. Die Verkehrsträgeraufteilung dieses Korridors ist keine Frachtentscheidung — sondern eine Entscheidung über die Wertdichte.

Installation

Erfordert Node ≥ 22.5 (nutzt das eingebaute SQLite — null native Abhängigkeiten, kein 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 lädt die Dateien direkt von balanca.economia.gov.br. Dieses Paket verteilt keine Daten weiter — die Datenbank wird auf Ihrer Maschine gebaut, immer frisch von der Quelle.

Nützliche Optionen:

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

Konfiguration im MCP-Client

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

COMEX_LANG akzeptiert pt (Standard) oder en. COMEX_DB überschreibt den Pfad zur Datenbank.

Die vier Tools

Die Caveats, die mit den Antworten geliefert werden

Zu simplified_regime_absent: Es gibt Verkehrsträger-Codes für POSTAL und COURIER, aber sie sind leer (13 Datensätze und 72 kg für China im gesamten Jahr 2026, gegenüber ~180 Millionen gemeldeter internationaler Sendungen). Sendungen mit geringem Wert laufen über das vereinfachte Verfahren und fließen nicht in die Handelsstatistik ein. Formale Statistik und Sendungsvolumen sind getrennte Welten — nicht addieren, nicht arithmetisch vergleichen.

Verifikation

Die Aggregate wurden per Kreuzimplementierung validiert: Derselbe Ausschnitt, verarbeitet durch einen awk-Durchlauf über die rohe CSV und durch die SQL-View dieses Servers, ergibt bis zur letzten Ziffer identische Zahlen (349.250 Datensätze, 7 Kanäle, Fracht- und Gewichtswerte).

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

Lizenz und Quelle

MIT. Daten: Comex Stat, Secretaria de Comércio Exterior / Receita Federal do Brasil (balanca.economia.gov.br) — öffentliche Quelle, beim Aufbau der Datenbank abgerufen.

Autor: Luis Delfin

Englisch

MCP-Server für brasilianische Außenhandelsdaten — mit den in der Antwort korrigierten Fallstricken des Datensatzes.

Vier Tools, die nicht lügen, statt vierzig, die nichts wissen.

Das Problem

Ein MCP-Server, der einen Datensatz nur exponiert, übergibt dem Agenten eine saubere API für eine falsche Zahl. Die Infrastruktur weiß nicht, dass das Feld lügt.

Brasiliens offizieller Handelsdatensatz (Comex Stat, veröffentlicht vom Foreign Trade Secretariat / Federal Revenue Service) hat einen Defekt, vor dem keine Dokumentation warnt:

Filtert man das Transportmodus-Feld nach AIR, erhält man 139,6 Mio. kg Importe aus China für Jan–Jul 2026. Kreuzt man dieselben Datensätze mit ihrem Verzollungspunkt, sind nur 34,0 Mio. (24 %) durch einen Flughafen gegangen. Die übrigen 89,7 Mio. wurden in Seehäfen verzollt und bestehen aus Ammoniumsulfat und Phosphatdünger — Fracht, die nicht fliegt, zu 0,29 US$/kg Fracht.

Unkorrigiert: Luftgewicht um 4,1× überhöht und Fracht pro kg um 70 % unterbewertet. Der Fehler ist still — nichts in der Abfrage weist darauf hin.

Dieser Server wendet die Korrektur an und liefert die Belege dafür, warum sie nötig ist.

Zwei Garantien

1. Jede Antwort enthält die bekannten Fehler, die für diese Abfrage gelten, mit gemessenen Belegen und Herkunft der Verifikation.

2. Die kritische Korrektur ist angewendet, nicht nur angekündigt. Der Kanal air bedeutet bereits „auf einem Flughafen abgefertigte Luftfracht“. Der kontaminierte Block bleibt absichtlich als air_declared_at_port abfragbar — für alle, die ihn prüfen möchten.

Was der Datensatz enthält, das veröffentlichte Zusammenfassungen verwerfen

Die Importdateien enthalten VL_FRETE und VL_SEGURO — Fracht und Versicherung, wie beim Zoll angegeben. Es ist das beste öffentlich verfügbare systematische Maß für realisierte Kosten, und fast niemand nutzt es.

China → Brasilien, Jan–Jul 2026, korrigiert:

Luftfracht kostet 76× mehr pro Kilogramm und nur 1,65× mehr pro Dollar Warenwert. Die Verkehrsträgeraufteilung dieses Korridors ist keine Frachtentscheidung — sondern eine Entscheidung über die Wertdichte.

Installation

Erfordert Node ≥ 22.5 (nutzt integriertes SQLite — null native Abhängigkeiten, kein node-gyp).

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

db:build lädt die Dateien direkt von balanca.economia.gov.br. Dieses Paket verteilt keine Daten weiter — die Datenbank wird auf Ihrem Rechner gebaut, immer frisch von der Quelle.

Die vier Tools

Verifikation

Die Aggregate wurden per Kreuzimplementierung validiert: Derselbe Ausschnitt, verarbeitet durch einen einzigen awk-Durchlauf über die rohe CSV und durch die SQL-View dieses Servers, ergibt bis zur letzten Ziffer identische Werte (349.250 Datensätze, 7 Kanäle, Fracht- und Gewichtswerte).

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

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