全球海关贸易数据 Mcp 服务
Overview
topease-customs-data
全球海关贸易数据 MCP 服务 — 提供 238 个国家/地区的进出口贸易数据查询能力。
简介
topease-customs-data 是一个 MCP（Model Context Protocol）服务器，对接 tradee.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-customs-mcp-server
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 配置方式（按优先级排序）：
- 环境变量（推荐）：设置
TOPEASE_MCP_API_KEY环境变量 - HTTP 请求头（streamable-http 模式）：通过
Authorization: Bearer <your_api_key>请求头传递
可用工具
search_customs_data
查询海关贸易数据。支持多维度联合过滤。
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|---|---|---|---|---|
company_name | string | 否 | 企业名称（模糊匹配进口商/出口商） | - |
product_keyword | string | 否 | 产品描述关键字，如 "led"、"valve" | - |
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 |
注意：
company_name、product_keyword、hs_code、country至少填写一个page_size最大值为 20，超出会自动截断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 编码查找国家 IDauth.py：API Key 验证模块，支持环境变量配置有效密钥列表setting.py：集中管理 API 基础地址和端口配置
本地开发
# 1. 克隆项目
git clone https://github.com/topease020/topease-customs-mcp-server.git
cd topease-customs-mcp-server
# 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！
联系方式
Server Config
{
"mcpServers": {
"topease-customs-data": {
"command": "uvx",
"args": [
"topease-mcp"
],
"env": {
"TOPEASE_MCP_API_KEY": "<YOUR_API_KEY>"
}
}
}
}Project Info
Created At
22 minutes agoUpdated At
21 minutes agoAuthor Name
topease020Star
-Language
-License
-Tags
Recommend Servers
View AllGotfreefax Mcp
@vannet
a day ago
Test
@modelcontextprotocol
test
6 months ago
Tavily Mcp
@tavily-ai
JavaScript
a year ago
Meteomatics
19 hours ago
Sentiment Analyzer
@DON-VXNKS
a day ago
Serper MCP Server
@garymengcom
A Serper MCP Server
Python
a year ago
Feedbug
@Joffrey Berrier
19 hours ago
Event4u/agent Config
@event4u-app
a day ago
Memory
@modelcontextprotocol
a year ago
Synx
2 days ago