mcp-comexstat

MCP Server for Comexstat API

This project implements an MCP (Model Context Protocol) server for the Comexstat API, allowing AI models like Claude to interact directly with Brazil's foreign trade data.

Overview

The MCP Comexstat server provides tools to query Brazilian export and import statistics, including:

General export and import data
Data by municipalities
Historical data (1989-1996)
Auxiliary tables with codes and descriptions

Features

Implemented using @modelcontextprotocol/sdk
Typing with TypeScript
Data validation with Zod
Support for communication via stdin/stdout (MCP standard)
Robust API error handling and responses

Installation

# Clone o repositório
git clone https://github.com/luizzzvictor/mcp-comexstat-easy.git
cd mcp-comexstat-easy

# Instale as dependências
npm install

# Compile o código TypeScript
npm run build

Quick Use

# Execute o servidor MCP
npm start

Available Tools

The MCP server provides the following tools:

General Data

getLastUpdate() - Gets the date the data was last updated
getAvailableYears() - Lists the years available for query
getAvailableFilters() - Lists available filters
getFilterValues(filter, language?) - Gets values for a specific filter
getAvailableFields() - Lists the fields available for detailing
getAvailableMetrics() - Lists available metrics
queryData(options) - Performs detailed queries with the following parameters:
- flow : "export" | "import"
- period : { from: "YYYY-MM", to: "YYYY-MM" }
- monthDetail : boolean
- filters : Array of filters (optional)
- details : Array of fields for detailing
- metrics : Array of metrics
- language : string (optional, default: "pt")

Data by Municipalities

queryMunicipalitiesData(options) - Query data focusing on municipalities

Historical Data

queryHistoricalData(options) - Query historical data (1989-1996)

Auxiliary Tables

getStates() - List Brazilian states
getStateDetails(ufId) - Details of a specific state
getCities() - List of cities
getCityDetails(cityId) - Details of a specific city
getCountries(search?) - List countries
getCountryDetails(countryId) - Details of a specific country
getEconomicBlocks(options?) - List economic blocks
getHarmonizedSystem(options?) - Harmonized System (HS)
getNBM(options?) - Brazilian Nomenclature of Goods
getNBMDetails(coNbm) - Details of a specific NBM code

Usage Example

// Consultar exportações para os EUA em 2023
const result = await queryData({
  flow: "export",
  period: { from: "2023-01", to: "2023-12" },
  monthDetail: false,
  filters: [{ filter: "country", values: [105] }],
  details: ["country", "month"],
  metrics: ["metricFOB", "metricKG"],
});

Integration with Claude

To use the MCP server with Claude Desktop:

Add the configuration to the claude_desktop_config.json file:
{ "mcpServers": { "comexstat": { "command": "node", "args": ["/caminho/completo/para/mcp-comexstat-easy/dist/index.js"] } } }
On Claude Desktop, use the command:
/mcp comexstat

Development

# Executar em modo de desenvolvimento
npm run dev

# Executar testes
npm test

# Verificar cobertura de testes
npm test -- --coverage

License

MIT