MCP Server para API Comexstat

Este projeto implementa um servidor MCP (Model Context Protocol) para a API Comexstat, permitindo que modelos de IA como Claude interajam diretamente com os dados de comércio exterior do Brasil.

Visão Geral

O servidor MCP Comexstat fornece ferramentas para consultar estatísticas de exportação e importação brasileiras, incluindo:

• Dados gerais de exportação e importação

• Dados por municípios

• Dados históricos (1989-1996)

• Tabelas auxiliares com códigos e descrições

Características

• Implementado usando @modelcontextprotocol/sdk

• Tipagem com TypeScript

• Validação de dados com Zod

• Suporte para comunicação via stdin/stdout (padrão MCP)

• Tratamento robusto de erros e respostas da API

Instalação

Uso Rápido

Ferramentas Disponíveis

O servidor MCP fornece as seguintes ferramentas:

Dados Gerais

• getLastUpdate() - Obtém a data da última atualização dos dados

• getAvailableYears() - Lista os anos disponíveis para consulta

• getAvailableFilters() - Lista os filtros disponíveis

• getFilterValues(filter, language?) - Obtém valores para um filtro específico

• getAvailableFields() - Lista os campos disponíveis para detalhamento

• getAvailableMetrics() - Lista as métricas disponíveis

• queryData(options) - Realiza consultas detalhadas com os seguintes parâmetros:

  • flow: "export" | "import"

  • period: { from: "YYYY-MM", to: "YYYY-MM" }

  • monthDetail: boolean

  • filters: Array de filtros (opcional)

  • details: Array de campos para detalhamento

  • metrics: Array de métricas

  • language: string (opcional, default: "pt")

Dados por Municípios

• queryMunicipalitiesData(options) - Consulta dados com foco em municípios

Dados Históricos

• queryHistoricalData(options) - Consulta dados históricos (1989-1996)

Tabelas Auxiliares

• getStates() - Lista estados brasileiros

• getStateDetails(ufId) - Detalhes de um estado específico

• getCities() - Lista municípios

• getCityDetails(cityId) - Detalhes de um município específico

• getCountries(search?) - Lista países

• getCountryDetails(countryId) - Detalhes de um país específico

• getEconomicBlocks(options?) - Lista blocos econômicos

• getHarmonizedSystem(options?) - Sistema Harmonizado (SH)

• getNBM(options?) - Nomenclatura Brasileira de Mercadorias

• getNBMDetails(coNbm) - Detalhes de um código NBM específico

Exemplo de Uso

Integração com Claude

Para usar o servidor MCP com Claude Desktop:

1. Adicione a configuração ao arquivo claude_desktop_config.json:

   { "mcpServers": { "comexstat": { "command": "node", "args": ["/caminho/completo/para/mcp-comexstat-easy/dist/index.js"] } } }

2. No Claude Desktop, use o comando:

   /mcp comexstat

Desenvolvimento

Licença

MIT