MCP Server for Comexstat API

此项目实现了用于Comexstat API的MCP（Model Context Protocol）服务器，允许像Claude这样的AI模型直接与巴西外贸数据进行交互。

概览

Comexstat MCP服务器提供了查询巴西进出口统计数据的工具，包括：

• 进出口总体数据
• 市级数据
• 历史数据（1989-1996）
• 包含代码和描述的辅助表

特性

• 使用@modelcontextprotocol/sdk实现
• TypeScript类型标注
• 使用Zod进行数据验证
• 支持通过stdin/stdout通信（MCP标准）
• 强健的错误处理和API响应

安装

bash

克隆仓库

git clone https://github.com/luizzzvictor/mcp-comexstat-easy.git
cd mcp-comexstat-easy

安装依赖

npm install

编译TypeScript代码

npm run build

快速使用

bash

启动MCP服务器

npm start

可用工具

MCP服务器提供以下工具：

总体数据

• getLastUpdate() - 获取数据最后更新日期
• getAvailableYears() - 列出可查询的年份
• getAvailableFilters() - 列出可用过滤器
• getFilterValues(filter, language?) - 获取特定过滤器的值
• getAvailableFields() - 列出可用于详细说明的字段
• getAvailableMetrics() - 列出可用指标
• queryData(options) - 使用以下参数执行详细查询：
  • flow: "export" | "import"
  • period: { from: "YYYY-MM", to: "YYYY-MM" }
  • monthDetail: boolean
  • filters: 过滤器数组（可选）
  • details: 用于详细说明的字段数组
  • metrics: 指标数组
  • language: string（可选，默认为"pt"）

市级数据

• queryMunicipalitiesData(options) - 查询以市级为重点的数据

历史数据

• queryHistoricalData(options) - 查询历史数据（1989-1996）

辅助表

• getStates() - 列出巴西各州
• getStateDetails(ufId) - 获取特定州的详情
• getCities() - 列出市镇
• getCityDetails(cityId) - 获取特定市镇的详情
• getCountries(search?) - 列出国家
• getCountryDetails(countryId) - 获取特定国家的详情
• getEconomicBlocks(options?) - 列出经济区块
• getHarmonizedSystem(options?) - 统一制度（HS）
• getNBM(options?) - 巴西商品命名法
• getNBMDetails(coNbm) - 获取特定NBM代码的详情

使用示例

typescript
// 查询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"],
});

与Claude集成

要将MCP服务器与Claude Desktop一起使用：

1. 在claude_desktop_config.json文件中添加配置：

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

2. 在Claude Desktop中使用命令：

   /mcp comexstat

开发

bash

以开发模式运行

npm run dev

运行测试

npm test

查看测试覆盖率

npm test -- --coverage

许可证

MIT