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 429 e erros temporários 5xx;
• 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.

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 build

Inicie o servidor:

npm start

Um 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() e getStateDetails(ufId);
• getCities() e getCityDetails(cityId);
• getCountries(search?) e getCountryDetails(countryId);
• getEconomicBlocks(options?);
• getHarmonizedSystem(options?);
• getNBM(options?) e getNBMDetails(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:

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:coverage

Licença

MIT