mcp-comex-brasil
mcp-comex-brasil
巴西外贸数据 MCP 服务器 — 响应中已修正数据集中的陷阱。
四个不撒谎的工具,而不是四十个不知情的工具。
这个服务器解决的问题
一个仅暴露数据集的 MCP 服务器,交付给代理的是一个通往错误数字的干净 API。管道不知道这个字段在撒谎。
Comex Stat — 巴西官方外贸数据库,由 Secretaria de Comércio Exterior / Receita Federal 发布 — 有一个任何文档都没有警告的缺陷:
按
AÉREA过滤运输方式字段,返回 2026 年(1–7 月)来自中国的进口 1.396 亿公斤。将这些相同记录与 清关点 交叉比对,只有 3400 万公斤(24%)经过机场。其余 8970 万公斤在 海运港口 清关,是硫酸铵和磷酸盐肥料——不会飞的货物,运费 US$0.29/kg。不修正的话:空运重量虚增 4.1 倍,每公斤运费被低估 70%。 这个错误是无声的:查询中没有任何迹象。
这个服务器应用修正,并返回说明为什么需要修正的证据。
Related MCP server: MCP Compras Públicas Brasil
两大保证
每个响应都包含适用于该查询的已知缺陷,并附有实测证据和验证来源。
关键修正已应用在结果中,而不仅仅是发出警告。
air渠道已经表示“在机场清关的空运”。被污染的数据块仍可作为air_declared_at_port查询——这是故意的,方便想要检查的人。
数据集拥有而已发布摘要丢弃的内容
进口文件带有 VL_FRETE 和 VL_SEGURO — 向海关申报的运费和保险费。这是公开可用的、对实际成本的最佳系统性度量,却几乎没有人使用它。
中国 → 巴西,2026 年 1–7 月,已修正:
渠道 | 重量(kg) | 运费 US$/kg | 运费占 FOB 的百分比 | 价值密度 |
空运(机场) | 33.993.130 | 10,81 | 9,37% | US$ 115,36/kg |
海运 | 16.074.641.185 | 0,142 | 5,68% | US$ 2,51/kg |
空运每公斤成本高出 76 倍,而每美元货物仅高出 1.65 倍。这个通道的运输方式划分不是运费决策——而是价值密度决策。
安装
需要 Node ≥ 22.5(使用内置 SQLite — 零原生依赖,不需要 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 SQLitedb:build 直接从 balanca.economia.gov.br 获取文件。本包不重新分发任何数据 — 数据库在您自己的机器上构建,始终从源头获取的新鲜数据。
有用的选项:
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在 MCP 客户端中的配置
{
"mcpServers": {
"comex": {
"command": "node",
"args": ["--experimental-sqlite", "/caminho/para/mcp-comex-brasil/dist/index.js"],
"env": { "COMEX_LANG": "pt" }
}
}
}COMEX_LANG 接受 pt(默认)或 en。COMEX_DB 覆盖数据库路径。
四个工具
工具 | 功能 |
| 按年份、月份、国家、NCM 和渠道统计价值、重量和价值密度。 |
| 按渠道统计申报的运费和保险费:US$/kg 和占 FOB 的百分比。仅限进口。 |
| 数据集的已知缺陷,附证据、修正规则和核查清单。 |
| 解析国家、NCM、运输方式和清关 URF(含机场/港口/其他分类)。 |
伴随响应的数据缺陷说明
id | 严重性 | 已修正? |
| 严重 | ✅ 自动(与清关点交叉比对) |
| 严重 | ❌ 不可能——源数据中不存在该数据 |
| 信息 | — |
| 警告 | ❌ 需要同比比较 |
关于 simplified_regime_absent:存在 POSTAL 和 COURIER 的运输方式代码,但它们是空的(2026 年全年中国只有 13 条记录和 72 公斤,而报告的国际包裹约为 1.8 亿件)。低价值货物通过简化制度处理,不计入贸易统计。正式统计与包裹量是两个互不相交的宇宙 — 不要相加,不要进行算术比较。
验证
聚合结果通过交叉实现进行了验证:同一数据切片,分别由对原始 CSV 执行的一次 awk 处理和本服务器的 SQL 视图处理,产生的数字直到最后一位都完全相同(349.250 条记录、7 个渠道、运费和重量值)。
npm test # 12 testes da lógica de classificação e do registro de caveats许可证与数据来源
MIT。数据:Comex Stat,Secretaria de Comércio Exterior / Receita Federal do Brasil(balanca.economia.gov.br)— 公共来源,在构建数据库时获取。
作者:Luis Delfin
英文
用于巴西外贸数据的 MCP 服务器 — 响应中已修正数据集的陷阱。
四个不撒谎的工具,而不是四十个不知情的工具。
问题
一个仅仅暴露数据集的 MCP 服务器,交付给代理的是一个通往错误数字的干净 API。管道不知道这个字段在撒谎。
巴西官方贸易数据集(Comex Stat,由 Foreign Trade Secretariat / Federal Revenue Service 发布)有一个任何文档都没有警告的缺陷:
按
AIR过滤运输方式字段,返回 2026 年 1–7 月来自中国的进口 1.396 亿公斤。将这些相同记录与它们的 清关点 交叉比对,只有 3400 万(24%)经过机场。其余 8970 万在 海港 清关,成分是硫酸铵和磷酸盐肥料——不会飞的货物,运费 US$0.29/kg。不修正的话:空运重量虚增 4.1 倍,每公斤运费被低估 70%。 这个错误是无声的——查询中没有任何标记。
这个服务器应用修正,并返回说明为什么需要修正的证据。
两大保证
每个响应都包含适用于该查询的已知缺陷,并附有实测证据和验证来源。
关键修正已应用,而不仅仅是发出警告。
air渠道已经表示“在机场清关的空运方式”。被污染的数据块仍可作为air_declared_at_port查询——这是故意的,方便任何想要检查它的人。
数据集拥有而已发布的摘要丢弃的内容
进口文件带有 VL_FRETE 和 VL_SEGURO — 向海关申报的运费和保险费。这是公开可用的、对实际成本的最佳系统性度量,却几乎无人使用。
中国 → 巴西,2026 年 1–7 月,已修正:
渠道 | 重量(kg) | 运费 US$/kg | 运费占 FOB 的百分比 | 价值密度 |
空运(机场清关) | 33,993,130 | 10.81 | 9.37% | US$115.36/kg |
海运 | 16,074,641,185 | 0.142 | 5.68% | US$2.51/kg |
空运每公斤成本高出 76 倍,而每美元货物仅高出 1.65 倍。这个通道的运输方式划分不是运费决策——而是价值密度决策。
安装
需要 Node ≥ 22.5(使用内置 SQLite — 零原生依赖,不需要 node-gyp)。
npm install && npm run build
npm run db:build -- --years 2025,2026 # fetches from the official source, builds SQLitedb:build 直接从 balanca.economia.gov.br 获取文件。本包不重新分发任何数据 — 数据库在您的机器上构建,始终从源头获取的新鲜数据。
四个工具
工具 | 功能 |
| 按年份、月份、国家、HS 编码和渠道统计价值、重量和价值密度。 |
| 按渠道统计申报的运费和保险费:US$/kg 和占 FOB 的百分比。仅限进口。 |
| 数据集的已知缺陷,附证据、修正规则和发布前核查清单。 |
| 解析国家、HS 编码、运输方式和清关单位(含机场/海港分类)。 |
验证
聚合结果通过交叉实现进行了验证:同一数据切片,分别由对原始 CSV 执行的一次 awk 处理和本服务器的 SQL 视图处理,产生的数字直到最后一位都完全相同(349,250 条记录、7 个渠道、运费和重量值)。
npm test # 12 tests covering the classification logic and the caveat registryMIT。数据:Comex Stat,Brazilian Foreign Trade Secretariat / Federal Revenue Service。作者:Luis Delfin
Available Tools
4 toolscomex_data_caveatsA
Defeitos conhecidos do dataset do Comex Stat, cada um com evidencia quantificada, regra de correcao e procedencia da verificacao. Use ANTES de publicar qualquer numero derivado desta fonte — inclui o checklist de conferencia. Esta tool responde a pergunta que um wrapper de dados nunca responde: este campo quer dizer o que parece?
Inputs: id.
comex_freight_costA
Frete e seguro DECLARADOS a aduana, por canal de transporte — em US$/kg e como % do valor FOB. Vem dos campos VL_FRETE e VL_SEGURO dos arquivos de importacao, que os resumos publicados descartam: e a melhor medida sistematica de custo realizado disponivel publicamente. Somente importacao (os arquivos de exportacao nao trazem frete). O canal 'air' ja esta corrigido pelo ponto de despacho.
Inputs: ncm, years, months, group_by, +1 more.
comex_resolve_codeA
Resolve codigos oficiais para nomes e vice-versa: pais, NCM, modal de transporte (VIA) e unidade da Receita de despacho (URF, com sua classificacao aeroporto/porto/outra). Necessario porque o dataset e todo codificado.
Inputs: kind (required), query (required), limit.
comex_trade_flowA
Fluxo de comercio exterior do Brasil (valor, peso e densidade de valor) a partir dos microdados aduaneiros oficiais do Comex Stat. Filtra por ano, mes, pais, NCM e canal de transporte, e agrupa como pedido. O canal 'air' JA vem corrigido pelo ponto de despacho — o campo de modal do dataset e contaminado e nao pode ser usado cru. A resposta inclui sempre os caveats aplicaveis e a procedencia dos arquivos.
Inputs: ncm, flow, limit, years, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The four tools have clearly distinct purposes: trade flow provides aggregated trade metrics, caveats explains data quality issues, freight cost focuses specifically on freight/insurance, and resolve_code handles code translation. There is no ambiguity in their scopes, and each tool addresses a separate aspect of working with the Comex Stat dataset.
All tools share the consistent 'comex_' prefix, which helps identify the server's domain. However, the naming patterns vary: three use noun phrases (trade_flow, data_caveats, freight_cost) while one uses a verb (resolve_code). This is a minor deviation, but the uniform prefix and clear terminology keep the set predictable.
With only four tools, the server is tightly scoped to the essential needs of querying Comex Stat data and understanding its caveats. Each tool is necessary and covers a distinct functional area, so the count is well-suited for the server's purpose without unnecessary bloat or trivial additions.
The tools cover the core workflows: querying trade flow, obtaining freight cost details, validating data quality through caveats, and resolving official codes. A minor gap is that freight data is only available for imports, but this is clearly stated and not a flaw in the tool design. Overall, the surface is sufficient for common analytical tasks.
Maintenance
Related MCP Connectors
Brazil Comex Stat MCP — Brazilian foreign trade statistics from MDIC (Ministério do…
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
AI-powered commodity price forecasts and Brazil trade intelligence via MCP. Access Brazilian exports and imports from MDIC/ComexStat since 2000, by HS4, HS6 and NCM code, partner country, USD FOB and kilograms — plus crop production, supply & demand, climate data and production forecasts for major commodities including soybeans, coffee, corn, beef and cocoa. Compare trade flows, markets, countries and time periods with like-for-like windows. Every answer identifies the measurement period and data source. 15 read-only tools. Metered in credits. Connect directly via Streamable HTTP — no installation required: https://mcp.kyrodata.com/mcp Authentication: Bearer key or OAuth 2.1 (PKCE). Official MCP registry: com.kyrodata/kyrodata
Trade Intel MCP — Compound tools that chain Comtrade, Census, Treasury,
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables querying official Brazilian Federal Revenue data on foreign trade habilitation (Radar), allowing users to check habilitation status directly from the official source. Read-only MCP server with a single consultation tool.MIT
- FlicenseCqualityBmaintenanceEnables read-only access to official Brazilian government procurement data from Compras.gov.br and the PNCP, covering all cataloged public GET endpoints through MCP tools.1751-
- AlicenseAqualityBmaintenanceBrazilian foreign trade from MDIC/ComexStat -- exports and imports since 2000 by HS code (SH4/SH6/NCM) and partner country, in USD FOB and kilograms -- plus crop production, supply-and-demand balances, climate readings and commodity forecasts for hubs such as soybean, coffee and beef. 15 read-only tools, remote at https://mcp.kyrodata.com/mcp; official registry com.kyrodata/kyrodata.151MIT
- AlicenseNot gradedqualityBmaintenanceEnables querying Brazilian public data through MCP tools, including IBGE geography, CNPJ/CEP/CPF lookups, BCB rates, FIPE vehicles, PNCP procurement, gazettes, OAB records, the slave-labour blacklist, and CNES health facilities, with local CPF validation.82 npmMIT