Skip to main content
Glama
mcp-comexstat

mcp-comexstat

by luizzzvictor

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.

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

Variável

Padrão

Finalidade

COMEXSTAT_API_URL

https://api-comexstat.mdic.gov.br

URL-base da API

COMEXSTAT_TIMEOUT_MS

30000

Tempo máximo de cada requisição

COMEXSTAT_MAX_RETRIES

4

Quantidade máxima de novas tentativas

COMEXSTAT_RETRY_BASE_DELAY_MS

1000

Espera inicial do recuo exponencial

COMEXSTAT_MIN_REQUEST_INTERVAL_MS

500

Intervalo mínimo entre chamadas

COMEXSTAT_QUERY_MIN_REQUEST_INTERVAL_MS

10000

Intervalo mínimo entre consultas de dados

COMEXSTAT_CACHE_TTL_MS

300000

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

Licença

MIT

Available Tools

20 tools
getAuxiliaryTableD

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

    D1.9/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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).

    Tool Count3/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP 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).
      100
      21
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Brazilian Chamber of Deputies open-data API, enabling search and retrieval of federal legislative bills and their status.
      15
      82 PyPI
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the Omie API to list products, consult clients, and create budgets
      MIT