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

Related MCP server: mcp-twitter

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:

1. Add the configuration to the claude_desktop_config.json file:

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

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