mcp-comexstat

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