topease-mcp 0.3.4

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/topease020/topease-customs-mcp-server.git
cd topease-mcp
uv pip install -e .

快速开始

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

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

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

或使用 pip 安装的版本：

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

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

公共服务地址

我们提供了公共的 streamable-http 服务，您可以直接使用以下配置：

配置项	值
服务类型	可流式传输的 HTTP (streamableHttp)
服务 URL	https://mcp.topease.net/mcp
请求头	Authorization=Bearer <your_api_key>

在大模型客户端中配置

在 Claude Desktop、Trae 等支持 streamable-http 的客户端中添加配置：

{
  "mcpServers": {
    "【PRO】TOPEASE 贸易数据查询 stream http": {
      "type": "streamableHttp",
      "url": "https://mcp.topease.net/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

API Key 配置说明

本服务支持两种 API Key 配置方式（按优先级排序）：

1. 环境变量（推荐）：设置 TOPEASE_MCP_API_KEY 环境变量
2. HTTP 请求头（streamable-http 模式）：通过 Authorization: Bearer <your_api_key> 请求头传递

可用工具

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、quantity、weight、uusd	tradedate
sort_order	string	否	排序方向：asc / desc	desc

注意：

1. company_name、product_keyword、hs_code、country 至少填写一个
2. page_size 最大值为 20，超出会自动截断
3. trade_type 映射：import→1, export→0, all→2

返回字段说明

每条记录包含以下字段（中文键名，便于大模型理解）：

字段	说明
单据ID	单据编号
海关编码	HS 海关编码
产品描述	产品描述
贸易类型	贸易类型（进口 / 出口）
进口商	进口商名称
出口商	出口商名称
数量	数量
数量单位	数量单位
重量	重量
金额(USD)	金额（USD），保留 4 位小数
贸易日期	贸易日期
原产国	原产国
原产国ID	原产国 ID

同时包含分页信息：

字段	说明
total	总记录数
page_index	当前页码
page_size	每页记录数
total_pages	总页数

使用示例

示例 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      # 模块入口：python -m topease_mcp
│       ├── main.py          # MCP 服务入口，FastMCP 服务器定义
│       ├── customs.py       # 海关数据模型与 API 调用服务
│       ├── country.py       # 238 个国家/地区数据（含 ISO 编码）
│       ├── auth.py          # API Key 认证模块
│       └── setting.py       # 配置项（API 地址、端口）
├── pyproject.toml           # 项目配置与依赖
├── README.md                # 项目文档
└── .env.example             # 环境变量示例

核心模块说明

• main.py：定义 FastMCP 服务器，注册 search_customs_data 工具，处理 API Key 认证逻辑
• customs.py：定义数据模型（CustomsRecord、CustomsQueryParams），封装 API 请求和响应处理
• country.py：包含 238 个国家/地区数据，支持通过名称、英文名、ISO 编码查找国家 ID
• auth.py：API Key 验证模块，支持环境变量配置有效密钥列表
• setting.py：集中管理 API 基础地址和端口配置

本地开发

# 1. 克隆项目
git clone https://github.com/topease020/topease-customs-mcp-server.git
cd topease-mcp

# 2. 安装依赖
uv sync

# 3. 运行测试（如果有）
uv run pytest

# 4. 本地运行
uv run python -m topease_mcp

常见问题

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

A: 支持全球 238 个国家和地区，包括主要贸易经济体。可通过中文名、英文名、ISO 2/3 位编码查询。

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

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

Q: 如何获取 API Key？

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

Q: 查询有什么限制？

A: API 有请求频率限制，具体限制请查看 API 文档。page_size 最大值为 20。

Q: 为什么工具参数中没有 api_key？

A: 为了简化大模型调用，API Key 通过环境变量或 HTTP 请求头配置，不再需要在每次调用时传入参数。

Q: 如何切换 stdio 和 streamable-http 模式？

A: 修改 main.py 中 mcp.run() 的 transport 参数即可：

• transport="stdio" — 桌面客户端模式
• transport="streamable-http" — Web 应用模式

许可证

MIT License - 详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 官网：https://tradee.topease.net/
• PyPI：https://pypi.org/project/topease-mcp/
• GitHub：https://github.com/topease020/topease-customs-mcp-server.git