mcp-comexstat
MCP Comex Stat
Servidor Model Context Protocol (MCP) para consultar a API oficial do Comex Stat, sistema de estatísticas de comércio exterior do Brasil mantido pelo MDIC.
Recursos
21 ferramentas MCP para exportações, importações, municípios, séries históricas e tabelas auxiliares;
validação dos parâmetros com Zod;
transporte MCP por
stdin/stdout;repetição automática com espera exponencial para respostas
429e erros temporários5xx;respeito ao cabeçalho HTTP
Retry-After;espaçamento configurável entre requisições;
cache temporário para metadados e consultas idempotentes;
validação normal de certificados TLS;
teste de saúde da API e teste automatizado do protocolo MCP.
Os dados vêm da API https://api-comexstat.mdic.gov.br. O MDIC também publica a base detalhada em CSV.
Related MCP server: br-eli-mcp
Requisitos
Node.js 18 ou versão posterior;
npm.
Instalação
git clone https://github.com/luizzzvictor/mcp-comexstat.git
cd mcp-comexstat
npm install
npm run buildInicie o servidor:
npm startUm cliente MCP pode executar o arquivo compilado com esta configuração:
{
"mcpServers": {
"comexstat": {
"command": "node",
"args": ["/caminho/absoluto/mcp-comexstat/dist/index.js"]
}
}
}Ferramentas
Saúde e metadados
healthCheck()— confirma o acesso à API, a data de atualização e os anos disponíveis;getLastUpdate()— informa a data da última atualização;getAvailableYears()— informa o intervalo anual disponível;getAvailableFilters()— lista filtros;getFilterValues(filter, language?)— lista valores aceitos por um filtro;getAvailableFields()— lista campos de detalhamento;getAvailableMetrics()— lista métricas.
Consultas
queryData(...)— consulta exportações ou importações gerais;queryMunicipalitiesData(...)— consulta dados por município;queryHistoricalData(...)— consulta a série histórica de 1989 a 1996.
Parâmetros principais de queryData:
flow: "export" | "import"
period: { from: "YYYY-MM", to: "YYYY-MM" }
monthDetail: boolean
filters: [{ filter: string, values: number[] }]
details: string[]
metrics: string[]
language: string (padrão: "pt")Exemplo de argumentos para consultar exportações brasileiras destinadas à Rússia:
{
"flow": "export",
"period": {
"from": "2026-01",
"to": "2026-06"
},
"monthDetail": false,
"filters": [
{
"filter": "country",
"values": [676]
}
],
"details": ["country"],
"metrics": ["metricFOB", "metricKG"],
"language": "pt"
}Use getCountries("Rússia") para descobrir o código 676 diretamente pela API.
Tabelas auxiliares
getAuxiliaryTable(table, search?, page?, pageSize?);getStates()egetStateDetails(ufId);getCities()egetCityDetails(cityId);getCountries(search?)egetCountryDetails(countryId);getEconomicBlocks(options?);getHarmonizedSystem(options?);getNBM(options?)egetNBMDetails(coNbm).
Controle de requisições
A API pode aplicar limites de frequência em períodos de uso intenso. O cliente organiza as chamadas em fila e repete respostas temporárias. As variáveis abaixo permitem ajustar esse comportamento:
Variável | Padrão | Finalidade |
|
| URL-base da API |
|
| Tempo máximo de cada requisição |
|
| Quantidade máxima de novas tentativas |
|
| Espera inicial do recuo exponencial |
|
| Intervalo mínimo entre chamadas |
|
| Intervalo mínimo entre consultas de dados |
|
| Validade do cache de respostas |
Mensagens operacionais são enviadas para stderr, preservando o stdout para o protocolo MCP.
Desenvolvimento
# Compilar
npm run build
# Executar testes unitários e de integração em memória
npm test
# Validar a comunicação MCP por stdio
npm run smoke
# Executar todas as verificações
npm run check
# Gerar cobertura
npm run test:coverageLicença
MIT
Available Tools
20 toolsgetAuxiliaryTableD
Inputs: table (required), page, pageSize, search.
getAvailableFieldsD
Inputs: no named parameters.
getAvailableFiltersD
Inputs: no named parameters.
getAvailableMetricsD
Inputs: no named parameters.
getAvailableYearsD
Inputs: no named parameters.
getCitiesD
Inputs: no named parameters.
getCityDetailsD
Inputs: cityId (required).
getCountriesD
Inputs: search.
getCountryDetailsD
Inputs: countryId (required).
getEconomicBlocksD
Inputs: add, language, search.
getFilterValuesD
Inputs: filter (required), language.
getHarmonizedSystemD
Inputs: add, language, page, perPage.
getLastUpdateD
Inputs: no named parameters.
getNBMD
Inputs: add, language, page, perPage, +1 more.
getNBMDetailsD
Inputs: coNbm (required).
getStateDetailsD
Inputs: ufId (required).
getStatesD
Inputs: no named parameters.
queryDataD
Inputs: details (required), flow (required), metrics (required), monthDetail (required), +3 more.
queryHistoricalDataD
Inputs: details (required), flow (required), metrics (required), period (required), +3 more.
queryMunicipalitiesDataD
Inputs: details (required), flow (required), metrics (required), period (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools have clearly distinct purposes targeting different data entities (countries, states, cities, NBM, etc.) or metadata (available fields, filters, metrics). However, some pairs like getCities/getMunicipalitiesData and getNBM/getNBMDetails have potential overlap that could cause confusion without descriptions to clarify their boundaries.
All tool names follow a consistent verb_noun pattern with 'get' or 'query' prefixes, using camelCase uniformly throughout. The naming is highly predictable and readable, with clear conventions for different types of operations (get for metadata/entities, query for data retrieval).
With 20 tools, this is borderline heavy for a trade statistics server. While the domain appears broad (covering countries, states, cities, NBM codes, auxiliary tables, etc.), the count feels somewhat inflated with multiple similar metadata tools (getAvailableFields/Filters/Metrics/Years) that might be consolidated.
The tool set appears to provide comprehensive coverage for trade data exploration and retrieval, including metadata discovery, entity lookups, and data querying across different dimensions (current, historical, municipal). Minor gaps might exist in data modification capabilities, but for a read-only statistical service, the surface seems reasonably complete.
Related MCP Connectors
Brazil Comex Stat MCP — Brazilian foreign trade statistics from MDIC (Ministério do…
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
Comtrade MCP — UN Comtrade API for international bilateral trade data
# MCP DadosBR Servidor MCP focado em dados públicos do Brasil. Oferece duas ferramentas simples e…
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP Server do SEI Pro para o SEI (Sistema Eletrônico de Informações) via API REST mod-wssei v2 + scraper do frontend web (modo híbrido).10021MIT
- AlicenseAqualityBmaintenanceMCP server for the Brazilian Chamber of Deputies open-data API, enabling search and retrieval of federal legislative bills and their status.1582 PyPI2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for the Omie API to list products, consult clients, and create budgetsMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides access to UK trade data from the ONS Trade Data API, enabling queries for trade statistics, metadata, and raw data.-