Servidor MCP de comércio exterior do Brasil — com as armadilhas do dataset corrigidas na resposta.
Quatro tools que não mentem, em vez de quarenta que não sabem.
Um servidor MCP que apenas expõe um dataset entrega ao agente uma API limpa para um número errado. A encanação não sabe que o campo mente.
O Comex Stat — a base oficial de comércio exterior do Brasil, publicada pela Secretaria de Comércio Exterior / Receita Federal — tem um defeito que nenhuma documentação avisa:
Filtrar o campo de modal por
AÉREAretorna 139,6 milhões de kg de importação da China em 2026 (jan–jul). Cruzando esses mesmos registros com o ponto de despacho, apenas 34,0 milhões (24%) passaram por um aeroporto. Os outros 89,7 milhões despacharam em portos marítimos e são sulfato de amônio e fertilizantes fosfáticos — carga que não voa, a US$0,29/kg de frete.Sem corrigir: peso aéreo 4,1× inflado e frete por quilo 70% subestimado. O erro é silencioso: nada na consulta acusa.
Este servidor aplica a correção, e devolve junto a evidência de por que ela é necessária.
Related MCP server: Receita Federal: Radar (Habilitação Comércio Exterior)
Toda resposta traz os defeitos conhecidos que se aplicam àquela consulta, com evidência medida e procedência da verificação.
A correção crítica está aplicada no resultado, não apenas avisada. O canal air já
significa "aéreo despachado em aeroporto". O bloco contaminado continua consultável como
air_declared_at_port, de propósito — para quem quiser inspecionar.
Os arquivos de importação carregam VL_FRETE e VL_SEGURO — frete e seguro declarados
à aduana. É a melhor medida sistemática de custo realizado disponível publicamente, e
praticamente ninguém a usa.
China → Brasil, jan–jul de 2026, já corrigido:
Canal | Peso (kg) | Frete US$/kg | Frete % do FOB | Densidade de valor |
Aéreo (aeroporto) | 33.993.130 | 10,81 | 9,37% | US$ 115,36/kg |
Marítimo | 16.074.641.185 | 0,142 | 5,68% | US$ 2,51/kg |
O aéreo custa 76× mais por quilo e apenas 1,65× mais por dólar de mercadoria. O split modal deste corredor não é uma decisão de frete — é uma decisão de densidade de valor.
Requer Node ≥ 22.5 (usa o SQLite embutido — zero dependências 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 SQLiteO db:build busca os arquivos direto de balanca.economia.gov.br. Nenhum dado é
redistribuído por este pacote — a base é construída na sua máquina, sempre fresca da fonte.
Opções úteis:
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{
"mcpServers": {
"comex": {
"command": "node",
"args": ["--experimental-sqlite", "/caminho/para/mcp-comex-brasil/dist/index.js"],
"env": { "COMEX_LANG": "pt" }
}
}
}COMEX_LANG aceita pt (default) ou en. COMEX_DB sobrescreve o caminho do banco.
Tool | O que faz |
| Valor, peso e densidade de valor por ano, mês, país, NCM e canal. O canal |
| Frete e seguro declarados por canal: US$/kg e % do FOB. Só importação. |
| Os defeitos conhecidos do dataset, com evidência, regra de correção e checklist de conferência. |
| Resolve país, NCM, modal e URF de despacho (com a classificação aeroporto/porto/outra). |
id | Severidade | Corrigido? |
| crítico | ✅ automático (cruzamento com o ponto de despacho) |
| crítico | ❌ impossível — o dado não existe na fonte |
| info | — |
| aviso | ❌ exige comparação interanual |
Sobre simplified_regime_absent: existem códigos de modal para POSTAL e COURIER, mas estão
vazios (13 registros e 72 kg para a China em todo 2026, contra ~180 milhões de encomendas
internacionais reportadas). As remessas de baixo valor passam pelo regime simplificado e não
entram nas estatísticas de comércio. Estatística formal e volume de encomenda são universos
disjuntos — não somar, não comparar aritmeticamente.
Os agregados foram validados por implementação cruzada: o mesmo recorte processado por uma
passada de awk sobre o CSV cru e pela view SQL deste servidor produz números idênticos até o
último dígito (349.250 registros, 7 canais, valores de frete e peso).
npm test # 12 testes da lógica de classificação e do registro de caveatsMIT. Dados: Comex Stat, Secretaria de Comércio Exterior / Receita Federal do Brasil
(balanca.economia.gov.br) — fonte pública, consultada em tempo de construção da base.
Autor: Luis Delfin
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.
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
AIRreturns 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.
Every response carries the known defects that apply to that query, with measured evidence and verification provenance.
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.
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:
Channel | Weight (kg) | Freight US$/kg | Freight % of FOB | Value density |
Air (airport-cleared) | 33,993,130 | 10.81 | 9.37% | US$115.36/kg |
Sea | 16,074,641,185 | 0.142 | 5.68% | US$2.51/kg |
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.
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 SQLitedb: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.
Tool | What it does |
| Value, weight and value density by year, month, country, HS code and channel. |
| Declared freight and insurance per channel: US$/kg and % of FOB. Imports only. |
| The dataset's known defects, with evidence, correction rule and a pre-publication checklist. |
| Resolves country, HS code, transport mode and clearance unit (with airport/seaport classification). |
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 registryMIT. Data: Comex Stat, Brazilian Foreign Trade Secretariat / Federal Revenue Service. Author: Luis Delfin
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?
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Um caveat especifico. Vazio = todos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It accurately describes a safe read-only behavior (retrieving caveat metadata) and discloses the internal structure of each result (evidence, correction rule, provenance). For a low-risk retrieval tool there is little behavioral hazard left uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, and the essential guidance fits in three sentences. The closing rhetorical question adds rhetorical color but no operational information, making it mildly less economical than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional enum parameter and no output schema, the description is reasonably complete: it explains what the results contain, when to invoke it, and the overall QA intent. It does not specify the return format, but that is a minor gap for this information-retrieval use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single 'id' parameter carries an enum and a clear explanation ('Um caveat especifico. Vazio = todos.'), so the schema already documents the parameter. The description adds no additional parameter-level detail, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exposes known defects of the Comex Stat dataset, each with quantified evidence, a correction rule, and verification provenance. It positions itself against 'a data wrapper' generically, distinguishing its QA purpose from the sibling trade-flow/freight tools, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance ('Use ANTES de publicar qualquer numero derivado desta fonte') and mentions a built-in conferencing checklist. However, it does not state when NOT to use it or name the alternatives (comex_trade_flow, comex_freight_cost) that it should be paired with.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| ncm | No | NCM completo ou prefixo. | |
| years | No | Anos, ex: [2025, 2026]. | |
| months | No | Meses 1-12. Vazio = todos. | |
| group_by | No | Dimensoes extra (o canal ja entra sempre). | |
| countries | No | Codigo, nome ou ISO3 do pais de origem. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses the data source (VL_FRETE and VL_SEGURO fields), the fact it is import-only, that air is corrected by despatch point, and the output units (US$/kg and % of FOB). It does not describe the response shape or potential limitations like missing data or aggregation behavior, but the key behavioral facts are present. A score of 4 reflects that the description goes beyond a bare statement of function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first defines the product and units, the second explains provenance and why it is valuable, the third states constraints (import-only and air correction). It is front-loaded with the core definition and avoids redundant words. No fluff or repetition of schema content. This is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no annotations. The description effectively communicates what the tool provides, but it does not describe the return format (e.g., whether it returns a table per channel, time series, or aggregated values). Since there is no output schema, the agent is left guessing at the response structure. While the core semantics are clear, the agent may need additional guidance on what to expect, making it incomplete for a complex data tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all 5 parameters, so the baseline is 3. The description does not add parameter-specific semantics beyond the schema; it mentions the channel is always included (which relates to group_by) but does not explain details like how NCM prefix matching works or how to combine years/months. The schema already describes each parameter clearly. Thus the description adds no extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (freight and insurance declared to customs by transport channel) and clearly distinguishes it from siblings by emphasizing it is the best systematic measure of realized cost. The verb is implicit ('provides') but the scope and source are explicit. It differentiates itself from comex_trade_flow (which likely covers flows) and comex_data_caveats (which explains caveats). This is a clear, distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear constraint: only imports, with export files lacking freight. It also states the air channel is corrected, which is a usage detail. It implies the tool should be used when realized cost is needed ('melhor medida sistematica de custo realizado'), but it does not explicitly name alternatives or say when not to use it. Thus it provides clear context and a condition, but stops short of explicit when-to-use vs. when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Tipo de codigo. | |
| limit | No | Maximo de resultados (default 20). | |
| query | Yes | Codigo exato ou parte do nome. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full responsibility for behavioral disclosure. It mentions bidirectional resolution and the URF classification, which adds specific context. However, it does not disclose return format, error handling, or whether partial matches are supported. For a simple lookup this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the core function and lists the code types, the second provides the rationale. There is no wasted wording, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema, no annotations), the description is essentially complete. It covers purpose, scope, and rationale. It could mention the return structure (e.g., list of matches) but the bidirectional resolver nature makes that non-critical for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining what each kind represents (e.g., VIA is modal de transporte, URF includes classification aeroporto/porto/outra) and clarifies that query can be a code or a name. This enriches the parameter semantics beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Resolve' with the resource 'codigos oficiais para nomes e vice-versa' and enumerates the exact code types (pais, NCM, VIA, URF) including URF's classification. This clearly distinguishes it from sibling tools like comex_trade_flow or comex_freight_cost, which handle completely different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: the dataset is all coded, so the tool should be used whenever codes need translating. While it doesn't explicitly state alternatives or when not to use it, the sibling tools are not viable alternatives for this function, so the lack of exclusion is acceptable. The rationale is enough for an agent to infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| ncm | No | NCM completo (8 digitos) ou prefixo, ex: '8517' ou '85'. | |
| flow | No | Sentido do fluxo. Default: import. | |
| limit | No | Maximo de linhas (default 50, max 500). | |
| years | No | Anos, ex: [2025, 2026]. | |
| months | No | Meses 1-12. Vazio = todos. | |
| channel | No | Canal corrigido. 'air' = modal aereo despachado em aeroporto. 'air_declared_at_port' expoe o bloco contaminado, para inspecao. | |
| group_by | No | Dimensoes de agrupamento. Default: ['year']. | |
| countries | No | Codigo, nome (PT/EN) ou ISO3. Ex: ['160'] ou ['China']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses significant behavioral details: the 'air' channel is corrected by dispatch point because the dataset's modal field is contaminated and should not be used raw, and the response always includes applicable caveats and file provenance. This is valuable transparency about data quality and output structure. It does not cover all typical behaviors (e.g., read-only nature, pagination, rate limits), but the critical data correction and output caveat information is highly informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and front-loaded with the main purpose. The first sentence states the core function, filters, and grouping; the second adds critical caveats about channel correction and response contents. There is no fluff, and the structure is efficient. It earns a 4 rather than 5 because it could be slightly more structured with bullets, but it is already clear and compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 8 parameters (all optional) and no output schema, the description covers key aspects: it specifies the metrics returned, the correction for the 'air' channel, and that responses always include caveats and file provenance. This is fairly complete for a data retrieval tool. However, it does not mention typical response format details (e.g., units, pagination, or whether results are aggregated by default), and it omits any prerequisites like authentication. These are minor gaps but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters already have explanatory text in the schema. The description text itself does not add new semantics for parameters beyond what the schema provides, even though the channel parameter's complex behavior is fully explained in the schema. According to the rubric, when schema coverage is high, the baseline is 3, and the description adds no additional value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides Brazil foreign trade flow data (value, weight, and value density) from official Comex Stat microdata, including filters and grouping. It mentions the specific resource and the metrics returned, making the purpose evident. It lacks an explicit verb like 'retrieve' but the noun-based phrasing is still clear. It is distinguishable from siblings, which focus on freight, code resolution, and caveats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not mention when to use this tool versus the sibling tools (comex_data_caveats, comex_freight_cost, comex_resolve_code). It provides no explicit conditions for selecting this tool over alternatives, nor any 'when not to use' guidance. The only implicit hint is that it covers trade flows, but that is not sufficient for guiding tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0comex_data_caveatscomex_freight_costcomex_resolve_codecomex_trade_flowScored 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.
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,
