topease-customs-mcp-server 0.3.1

MCP server for customs trade data query - 海关贸易数据查询MCP服务

topease-customs-data

全球海关贸易数据 MCP 服务 — 提供 238 个国家/地区的进出口贸易数据查询能力。

简介

topease-customs-data 是一个 MCP（Model Context Protocol）服务器，对接 topease.net 海关智能体贸易数据平台，支持按进出口企业名称、产品关键字、HS编码、贸易时间、进出口类型及国家/市场/地区进行多维度联合查询，帮助大模型快速获取真实的全球贸易情报数据。

使用前需在 https://tradee.topease.net/ 注册并获取 API Key。

特性

• 🌍 全球覆盖：支持 238 个国家/地区的贸易数据查询
• 🔍 多维度查询：企业名称、产品关键字、HS 编码、贸易时间、进出口类型、国家联合筛选
• 🔐 安全认证：支持 API Key 认证，保护数据访问安全
• 🚀 两种传输模式：支持 stdio（桌面客户端）和 streamable-http（Web 应用）两种运行模式
• 📊 丰富的返回字段：包含企业信息、产品详情、贸易金额、数量、重量等完整数据

安装

使用 pip

pip install topease-mcp

使用 uv

uv add topease-mcp

使用 uvx（免安装，直接运行）

uvx topease-mcp

从源码安装

git clone https://github.com/huiyitony/TOPEASE-MCP
cd topease-mcp
uv pip install -e .

快速开始

方式一：stdio 模式（推荐用于 Claude Desktop、Trae 等桌面客户端）

在 Claude Desktop、Trae 等 MCP 客户端的配置文件中添加：

{
  "mcpServers": {
    "topease-customs-data": {
      "type": "stdio",
      "command": "uvx",
      "args": ["topease-mcp"],
      "env": {
        "TOPEASE_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

或使用 pip 安装的版本：

{
  "mcpServers": {
    "topease-customs-data": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "topease_mcp"],
      "env": {
        "TOPEASE_MCP_API_KEY": "<YOUR_API_KEY>"
    }
  }
}

方式二：streamable-http 模式（推荐用于 Web 应用）

创建 .env 文件配置环境变量：

然后启动服务器：

uvx topease-mcp --transport streamable-http

或使用 Python 模块：

python -m topease_mcp

环境变量配置

环境变量	说明	默认值
TOPEASE_MCP_API_KEY	API 密钥，从 https://tradee.topease.net/ 获取	-

可用工具

search_customs_data

查询海关贸易数据。支持多维度联合过滤。

参数	类型	必填	说明	默认值
company_name	string	否	企业名称（模糊匹配进口商/出口商）	-
product_keyword	string	否	产品描述关键字，如 "led"、"手机"	-
hs_code	string	否	HS 海关编码（前缀匹配），如 "8415"	-
trade_type	string	否	贸易类型：import（进口）、export（出口）、all（全部）	all
country	string	否	国家/地区名称（中文/英文/ISO编码均可），如 "China"、"美国"、"JP"	-
date_from	string	否	起始日期，格式 YYYY-MM-DD	-
date_to	string	否	结束日期，格式 YYYY-MM-DD	-
page_index	int	否	页码	1
page_size	int	否	每页记录数（最大 20）	20
sort_by	string	否	排序字段	tradedate
sort_order	string	否	排序方向：asc / desc	desc

注意：

1. api_key 参数可选，当使用 streamable-http 模式时，也可以通过 HTTP 请求头 Authorization: Bearer your_api_key 传递
2. company_name、product_keyword、hs_code、country 至少填写一个

返回字段说明

每条记录包含以下字段：

字段	说明
bill_id	单据编号
country_id	国家 ID
country_name	国家中文名
country_enname	国家英文名
country_code2	国家 ISO 2 位编码
country_code3	国家 ISO 3 位编码
trade_type	贸易类型（import / export）
hs_code	HS 海关编码
prodesc	产品描述
importer_name	进口商名称
exporter_name	出口商名称
quantity	数量
quantity_unit	数量单位
weight	重量
amount_usd	金额（USD）
trade_date	贸易日期
origin_country	原产国

使用示例

示例 1：按产品关键字查询

请帮我查一下 LED 产品2025年从美国的进口数据前5条贸易数据

大模型将自动调用：

{
  "product_keyword": "led",
  "country": "美国",
  "trade_type": "import", 
  "date_from": "2025-01-01",
  "date_to": "2025-12-31",
  "page_index": 1,
  "page_size": 5 
}

示例 2：按企业名称查询

查询IKEA SUPPLY AG公司 2025 年从美国出口记录

{
  "company_name": "IKEA SUPPLY AG",
  "country": "美国",
  "trade_type": "export",
  "date_from": "2025-01-01",
  "date_to": "2025-12-31"
}

示例 3：按国家和 HS 编码查询

查询日本 8415 类目下的进口贸易数据

{
  "country": "Japan",
  "hs_code": "8415",
  "trade_type": "import"
}

示例 4：使用 HTTP 请求头传递 API Key（streamable-http 模式）

curl -X POST https://mcp.topease.net/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "name": "search_customs_data",
    "parameters": {
      "product_keyword": "CABIN",
      "page_index": 1,
      "page_size": 10
    }
  }'

开发指南

项目结构

topease-mcp/
├── src/topease_mcp/
│   ├── __init__.py      # 包初始化
│   ├── __main__.py      # 模块入口
│   ├── main.py          # MCP 服务入口，FastMCP 服务器定义
│   ├── customs.py       # 海关数据模型与 API 调用服务
│   ├── country.py       # 238 个国家/地区数据（含 ISO 编码）
│   ├── auth.py          # API Key 认证模块
│   └── setting.py       # 配置项
├── pyproject.toml       # 项目配置与依赖
└── README.md

常见问题

Q: 支持哪些国家/地区？

A: 支持全球 238 个国家和地区，包括主要贸易经济体。

Q: 数据更新频率是多少？

A: 数据定期更新，具体请参考 topease.net 官网说明。

Q: 如何获取 API Key？

A: 访问 https://tradee.topease.net/ 注册账号即可获取。

Q: 查询有什么限制？

A: API 有请求频率限制，具体限制请查看 API 文档。

许可证

MIT License - 详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 官网：https://tradee.topease.net/
• PyPI：https://pypi.org/project/topease-mcp/
• GitHub：https://github.com/huiyitony/TOPEASE-MCP