Skip to main content
Glama
mcp-comex-brasil
by PHIAI-IO

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

两大保证

  1. 每个响应都包含适用于该查询的已知缺陷,并附有实测证据和验证来源。

  2. 关键修正已应用在结果中,而不仅仅是发出警告。 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 SQLite

db: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 覆盖数据库路径。

四个工具

工具

功能

comex_trade_flow

按年份、月份、国家、NCM 和渠道统计价值、重量和价值密度。air 渠道已预先修正。

comex_freight_cost

按渠道统计申报的运费和保险费:US$/kg 和占 FOB 的百分比。仅限进口。

comex_data_caveats

数据集的已知缺陷,附证据、修正规则和核查清单。

comex_resolve_code

解析国家、NCM、运输方式和清关 URF(含机场/港口/其他分类)。

伴随响应的数据缺陷说明

id

严重性

已修正?

via_contamination

严重

✅ 自动(与清关点交叉比对)

simplified_regime_absent

严重

❌ 不可能——源数据中不存在该数据

declared_not_audited

信息

—

monthly_volatility

警告

❌ 需要同比比较

关于 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%。 这个错误是无声的——查询中没有任何标记。

这个服务器应用修正,并返回说明为什么需要修正的证据。

两大保证

  1. 每个响应都包含适用于该查询的已知缺陷,并附有实测证据和验证来源。

  2. 关键修正已应用,而不仅仅是发出警告。 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 SQLite

db:build 直接从 balanca.economia.gov.br 获取文件。本包不重新分发任何数据 — 数据库在您的机器上构建,始终从源头获取的新鲜数据。

四个工具

工具

功能

comex_trade_flow

按年份、月份、国家、HS 编码和渠道统计价值、重量和价值密度。air 已预先修正。

comex_freight_cost

按渠道统计申报的运费和保险费:US$/kg 和占 FOB 的百分比。仅限进口。

comex_data_caveats

数据集的已知缺陷,附证据、修正规则和发布前核查清单。

comex_resolve_code

解析国家、HS 编码、运输方式和清关单位(含机场/海港分类)。

验证

聚合结果通过交叉实现进行了验证:同一数据切片,分别由对原始 CSV 执行的一次 awk 处理和本服务器的 SQL 视图处理,产生的数字直到最后一位都完全相同(349,250 条记录、7 个渠道、运费和重量值)。

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

MIT。数据:Comex Stat,Brazilian Foreign Trade Secretariat / Federal Revenue Service。作者:Luis Delfin

Available Tools

4 tools
comex_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

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Brazilian 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.
      15
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT