How do I use topease-customs-data?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@topease-customs-data 查询美国2025年LED产品的进口数据" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

topease-customs-data

by topease020

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

全球海关贸易数据 MCP

全球海关贸易数据 MCP 服务 — 覆盖 238 个国家/地区，一站式查询进出口贸易明细与采购商、供应商企业画像分析。

简介

全球海关贸易数据 MCP 是一个 MCP（Model Context Protocol）服务器，对接 tradee.topease.net 海关智能体贸易数据平台。内置 15 个工具：海关贸易明细查询、采购商（Importer）/供应商（Exporter）企业搜索，以及围绕两大主体的关键字、贸易角色、HS 编码、贸易港口、贸易趋势、交易对手等多维度分析能力，帮助大模型快速获取真实的全球贸易情报数据。

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

Related MCP server: mcp-comtrade

特性

🌍 全球覆盖：支持 238 个国家/地区的贸易数据查询
🔍 多维度查询：企业名称、产品关键字、HS 编码、贸易时间、进出口类型、国家联合筛选
🔐 安全认证：支持 API Key 认证，保护数据访问安全
🚀 两种传输模式：支持 stdio（桌面客户端）和 streamable-http（Web 应用）两种运行模式
📊 丰富的返回字段：包含企业信息、产品详情、贸易金额、数量、重量等完整数据
🧭 双主体多维分析：围绕采购商（importer）与供应商（exporter）各提供 7 个分析工具，覆盖关键字、贸易角色、HS 编码、港口、趋势、交易对手等维度

安装

使用 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> 请求头传递

可用工具

当前共注册 15 个工具：

分类	工具	说明
海关贸易数据查询	`search_customs_data`	海关贸易明细查询
采购商搜索	`search_importer_data`	采购商（进口商）企业搜索
采购商分析	`importer_keyword_analysis`	贸易关键字统计
采购商分析	`importer_role_analysis`	贸易角色分布
采购商分析	`importer_hscode_analysis`	贸易编码（HS Code）统计
采购商分析	`importer_port_analysis`	贸易港口统计
采购商分析	`importer_cycle_analysis`	贸易趋势（按月统计）
采购商分析	`importer_exporter_analysis`	贸易供应商（上游）列表
供应商搜索	`search_exporter_data`	供应商（出口商）企业搜索
供应商分析	`exporter_keyword_analysis`	贸易关键字统计
供应商分析	`exporter_role_analysis`	贸易角色分布
供应商分析	`exporter_hscode_analysis`	贸易编码（HS Code）统计
供应商分析	`exporter_port_analysis`	贸易港口统计
供应商分析	`exporter_cycle_analysis`	贸易趋势（按月统计）
供应商分析	`exporter_importer_analysis`	贸易采购商（客户）列表

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`	总页数

search_importer_data

查询海关数据中的采购商（进口商）企业。支持按产品关键字、HS 编码、企业名称、国家等多维度检索，返回采购商 TCode，可作为后续各 importer_* 分析工具的入参。

参数	类型	必填	说明	默认值
`prodesc`	string	否	产品描述关键字，如 "led"	-
`hs_code`	string	否	HS 海关编码	-
`company_name`	string	否	采购商企业名称关键字	-
`country`	string	否	企业所在国家（中文名/英文名/ISO 编码均可）	-
`from_country`	string	否	采购来源国，如 "China" 表示筛选从中国采购过的采购商	-
`recent_years`	string	否	查询近几年的交易数据，范围 1-5	`"1"`
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`amount`、`count`、`quantity`、`weight`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

注意：prodesc、hs_code、company_name 至少填写一项。

返回字段（records 列表每个元素）：

字段	类型	说明
`TCode`	Encryption	采购商 TCode（唯一标识，用于后续分析工具）
`name`	String	企业名称
`countryId`	Long	企业所在国家 ID
`relatedCount`	Long	相关交易单数
`totalCount`	Long	总交易单数
`maxTradeDate`	String	企业最近贸易时间
`relatedHsCode`	String	关联产品编码
`relatedProduct`	String	关联产品描述

附加注入字段：countryCnName / countryName（企业所在国家中英文名）、fromCountryCnName / fromCountryName（采购来源国中英文名）。

search_exporter_data

查询海关数据中的供应商（出口商）企业。参数结构与 search_importer_data 一致，差异点：to_country 为销售目的国。

参数	类型	必填	说明	默认值
`prodesc`	string	否	产品描述关键字，如 "led"	-
`hs_code`	string	否	HS 海关编码	-
`company_name`	string	否	供应商企业名称关键字	-
`country`	string	否	企业所在国家（中文名/英文名/ISO 编码均可）	-
`to_country`	string	否	销售目的国，如 "United States" 表示筛选销售到美国的供应商	-
`recent_years`	string	否	查询近几年的交易数据，范围 1-5	`"1"`
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`amount`、`count`、`quantity`、`weight`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）： 与 search_importer_data 相同（TCode 为供应商 TCode）；附加注入字段为 countryCnName / countryName、toCountryCnName / toCountryName（销售目的国中英文名）。

importer_cycle_analysis

查询指定采购商的贸易趋势（按月统计）。传入采购商 TCode，按月返回贸易次数、金额、数量、重量、箱量，可用于观察采购商的贸易季节性和周期性变化。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode）。可先通过 `search_importer_data` 工具查询采购商获取	-
`hs_code`	string	否	HS 海关编码前缀过滤	-
`prodesc`	string	否	提单描述关键字，进一步过滤结果	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数，默认 `"12"`（对应 12 个月）	`"12"`
`sort_field`	string	否	排序字段：`tradeDate`、`quantity`、`weight`、`amount`、`count`	`"tradeDate"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`tradeDate`	String	交易月份，如 `"2025-01"`
`teus`	Decimal	贸易总箱量（TEU）
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`quantity`	Decimal	贸易总数量
`weight`	Decimal	贸易总重量

同时包含分页字段：total、pageSize、pageIndex。

importer_keyword_analysis

查询指定采购商的企业关联产品关键字统计，了解该采购商主要采购哪些产品。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode），可通过 `search_importer_data` 获取	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`

返回字段（records 列表每个元素）：

字段	类型	说明
`keyword`	String	关键字
`count`	Long	贸易次数
`countPercent`	Decimal	贸易次数占比

importer_role_analysis

查询指定采购商的贸易角色分布（采购商/供应商）及数据源国家、数据源类型。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode）	-
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`role`	String	贸易角色（采购商/供应商）
`dataSourceCountry`	String	数据源国家，如 "美国,加拿大"
`dataSourceType`	String	数据源类型（进口/出口）
`amount`	Decimal	贸易总金额
`count`	Long	贸易总次数
`amountPercent`	Decimal	贸易金额占比
`countPercent`	Decimal	贸易次数占比

importer_hscode_analysis

查询指定采购商的 HS 编码维度贸易统计，含各维度占比及中英文海关编码描述。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`hsCode`	String	HS 编码
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`teus`	Decimal	贸易总箱量
`weight`	Decimal	贸易总重量
`quantity`	Decimal	贸易总数量
`amountPercent` / `countPercent` / `quantityPercent` / `weightPercent` / `teusPercent`	Decimal	金额/次数/数量/重量/箱量占比
`cnDescription`	String	中文海关编码描述
`enDescription`	String	英文海关编码描述

importer_port_analysis

查询指定采购商的港口维度贸易统计（起运港/卸货港）。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数，最大 `"10"`，超出自动截断	`"10"`
`port_type`	string	否	港口类型：`1` 起运港口，`2` 卸货港口	`"2"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`port`	String	港口名称
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`weight`	Decimal	贸易总重量
`quantity`	Decimal	贸易总数量
`teus`	Decimal	贸易总箱量
`amountPercent` / `quantityPercent` / `countPercent` / `teusPercent` / `weightPercent`	Decimal	金额/数量/次数/箱量/重量占比

importer_exporter_analysis

查询指定采购商的贸易供应商（上游）列表，了解该采购商从哪些供应商采购、各占多少份额。

参数	类型	必填	说明	默认值
`t_code`	string	是	采购商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`TCode`	String	供应商 Tcode
`supplierName`	String	供应商名称
`countryId`	Long	企业所在国家 ID
`teus` / `weight` / `quantity`	Decimal	贸易总箱量 / 总重量 / 总数量
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`amountPercent` / `countPercent` / `quantityPercent` / `weightPercent` / `teusPercent`	Decimal	金额/次数/数量/重量/箱量占比

exporter_cycle_analysis

查询指定供应商的贸易趋势（按月统计）。传入供应商 TCode，按月返回贸易次数、金额、数量、重量、箱量，可用于观察供应商的贸易季节性和周期性变化。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode）。可先通过 `search_exporter_data` 工具查询供应商获取	-
`hs_code`	string	否	HS 海关编码前缀过滤	-
`prodesc`	string	否	提单描述关键字，进一步过滤结果	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数，默认 `"12"`（对应 12 个月）	`"12"`
`sort_field`	string	否	排序字段：`tradeDate`、`quantity`、`weight`、`amount`、`count`	`"tradeDate"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`tradeDate`	String	交易月份，如 `"2025-01"`
`teus`	Decimal	贸易总箱量（TEU）
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`quantity`	Decimal	贸易总数量
`weight`	Decimal	贸易总重量

同时包含分页字段：total、pageSize、pageIndex。

exporter_keyword_analysis

查询指定供应商的企业关联产品关键字统计，了解该供应商主要供应哪些产品。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode），可通过 `search_exporter_data` 获取	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`

返回字段（records 列表每个元素）：

字段	类型	说明
`keyword`	String	关键字
`count`	Long	贸易次数
`countPercent`	Decimal	贸易次数占比

exporter_role_analysis

查询指定供应商的贸易角色分布及数据源国家、数据源类型。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode）	-
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`role`	String	企业角色
`dataSourceCountry`	String	数据源国家
`dataSourceType`	String	数据源类型（进口/出口）
`count`	Long	贸易次数
`amount`	Decimal	贸易总金额
`amountPercent`	Decimal	贸易金额占比
`countPercent`	Decimal	贸易次数占比

exporter_hscode_analysis

查询指定供应商的 HS 编码维度贸易统计，含各维度占比及中英文海关编码描述。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）： 与 importer_hscode_analysis 相同（hsCode、count、amount、teus、weight、quantity、各维度 *Percent、cnDescription、enDescription）。

exporter_port_analysis

查询指定供应商的港口维度贸易统计。与 importer_port_analysis 参数一致，差异点：port_type 默认为 "1"（起运港口，供应商视角）。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数，最大 `"10"`，超出自动截断	`"10"`
`port_type`	string	否	港口类型：`1` 起运港口，`2` 卸货港口	`"1"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）： 与 importer_port_analysis 相同（port、count、amount、weight、quantity、teus、各维度 *Percent）。

exporter_importer_analysis

查询指定供应商的贸易采购商（客户）列表，了解该供应商把货卖给哪些采购商、各占多少份额。

参数	类型	必填	说明	默认值
`t_code`	string	是	供应商 ID（TCode）	-
`prodesc`	string	否	提单描述关键字	-
`hs_code`	string	否	HS 编码	-
`b_date`	string	否	交易起始日期，格式 `yyyy-MM-dd`	-
`e_date`	string	否	交易结束日期，格式 `yyyy-MM-dd`	-
`page_index`	string	否	页码	`"1"`
`page_size`	string	否	每页记录数	`"10"`
`sort_field`	string	否	排序字段：`quantity`、`weight`、`amount`、`count`、`teus`	`"amount"`
`sort_type`	string	否	排序方向：`desc` / `asc`	`"desc"`

返回字段（records 列表每个元素）：

字段	类型	说明
`TCode`	String	采购商 Tcode
`importerName`	String	采购商名称
`countryId`	Long	企业所在国家 ID
`amount`	Decimal	贸易总金额
`teus` / `weight` / `quantity`	Decimal	贸易总箱量 / 总重量 / 总数量
`count`	Long	贸易次数
`amountPercent` / `countPercent` / `quantityPercent` / `weightPercent` / `teusPercent`	Decimal	金额/次数/数量/重量/箱量占比

使用示例

示例 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
    }
  }'

示例 5：采购商全维度分析工作流（多工具联动）

帮我分析一下美国的 LED 采购商，并给出其中最大采购商的采购趋势和供应商构成

大模型将依次调用：

// 第 1 步：搜索采购商，获取 TCode
{ "tool": "search_importer_data", "parameters": { "prodesc": "led", "country": "美国" } }

// 第 2 步：查看采购趋势（按月）
{ "tool": "importer_cycle_analysis", "parameters": { "t_code": "<第1步返回的TCode>" } }

// 第 3 步：查看供应商构成
{ "tool": "importer_exporter_analysis", "parameters": { "t_code": "<第1步返回的TCode>" } }

供应商维度同理：先用 search_exporter_data 获取供应商 TCode，再调用 exporter_* 系列分析工具。

开发指南

项目结构

topease-mcp/
├── src/
│   └── topease_mcp/
│       ├── __init__.py                  # 包初始化
│       ├── __main__.py                  # 模块入口：python -m topease_mcp
│       ├── main.py                      # MCP 服务入口：FastMCP 服务器定义、共享鉴权逻辑与工具注册
│       ├── main_stdio.py                # stdio 模式独立入口
│       ├── auth.py                      # API Key 认证模块
│       ├── country.py                   # 238 个国家/地区数据（含 ISO 编码）
│       ├── setting.py                   # 配置项（API 地址、端口）
│       └── mcp_services/                # MCP 服务目录（每个服务 = Service 层 + 工具注册层）
│           ├── customs_search/              # 海关贸易明细搜索（search_customs_data）
│           ├── importer_search/             # 采购商企业搜索（search_importer_data）
│           ├── exporter_search/             # 供应商企业搜索（search_exporter_data）
│           ├── importer_keyword_analysis/   # 采购商-贸易关键字
│           ├── importer_role_analysis/      # 采购商-贸易角色
│           ├── importer_hscode_analysis/    # 采购商-贸易编码
│           ├── importer_port_analysis/      # 采购商-贸易港口
│           ├── importer_cycle_analysis/     # 采购商-贸易趋势
│           ├── importer_exporter_analysis/  # 采购商-贸易供应商
│           ├── exporter_keyword_analysis/   # 供应商-贸易关键字
│           ├── exporter_role_analysis/      # 供应商-贸易角色
│           ├── exporter_hscode_analysis/    # 供应商-贸易编码
│           ├── exporter_port_analysis/      # 供应商-贸易港口
│           ├── exporter_cycle_analysis/     # 供应商-贸易趋势
│           └── exporter_importer_analysis/  # 供应商-贸易采购商
├── pyproject.toml                       # 项目配置与依赖
├── README.md                            # 项目文档
└── .env.example                         # 环境变量示例

每个服务目录包含固定三个文件：__init__.py、<ServiceName>Services.py（Service 层：参数/结果数据模型 + API 请求封装）、<tool_name>.py（工具注册层：注册 MCP 工具并处理鉴权与参数校验）。

核心模块说明

main.py：定义 FastMCP 服务器与共享鉴权逻辑（TOPEASE_MCP_API_KEY、_get_api_key_from_headers、_format_error），各工具注册文件由此导入
mcp_services/：15 个 MCP 工具的实现目录，Service 层封装 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-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！

联系方式

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

The Company Atlas
io.github.IndoTender
Global customs trade data and company registry. Search shipments, and look up legal entities.
Search Government Data Research & Data
2
https://thecompanyatlas.com/mcp
un-comtrade-mcp-server A
io.github.cyanheads
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
Open Data Government Data
914
https://un-comtrade.caseyjhand.com/mcp
Trade Intel A
io.github.pipeworx-io
Trade Intel MCP — Compound tools that chain Comtrade, Census, Treasury,
Government Data Open Data Research & Data
472
https://gateway.pipeworx.io/trade-intel/mcp
Nexscope DOAuth
io.github.nexscope
Ecommerce data MCP: Amazon, TikTok Shop, Walmart, Temu, Ozon, Shopee, 1688, Etsy, eBay & more
E-commerce & Retail Data Platforms
55619
https://api.nexscope.ai/mcp

Related MCP Servers

estore-mcp-server
E-commerce & Retail Search Research & Data
handaas
F
license
Not graded
quality
B
maintenance
Provides comprehensive enterprise e-commerce data including global store profiles, product category statistics, and sales performance analysis. It enables users to search for companies and evaluate their domestic and international e-commerce business layouts across various platforms.
Updated 4 days ago (2026-10-28 10:31 UTC)
2
-
mcp-comtrade
Finance Research & Data Open Data
pipeworx-io
A
license
Not graded
quality
B
maintenance
Provides access to UN Comtrade international bilateral trade data via an MCP server, enabling AI agents to query trade statistics through natural language.
Updated 3 days ago (2026-10-29 02:16 UTC)
254 npm
MIT
procureradar-buyer
Research & Data E-commerce & Retail
tonyback0101-cmyk
A
license
Not graded
quality
D
maintenance
MCP server for global B2B buyer intelligence. Find verified importers & distributors by product category & country. Free anonymous discovery via find_buyers. Contact unlock & company intelligence require a zk_ API key. SGX-listed data provider, PDPA compliant, bilingual EN/ZH.
Updated 5 months ago (2026-05-30 09:09 UTC)
8 npm
MIT
全球海关贸易数据 MCPofficial
Government Data Research & Data Search
TopEase-AI
A
license
B
quality
D
maintenance
提供全球238个国家/地区的进出口贸易数据查询，支持按企业名称、产品关键字、HS编码等多维度联合搜索。
Updated 5 months ago (2026-06-13 14:38 UTC)
1
MIT

全球海关贸易数据 MCP

简介

特性

安装

使用 pip

使用 uv

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

从源码安装

快速开始

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

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

公共服务地址

在大模型客户端中配置

API Key 配置说明

可用工具

search_customs_data

返回字段说明

search_importer_data

search_exporter_data

importer_cycle_analysis

importer_keyword_analysis

importer_role_analysis

importer_hscode_analysis

importer_port_analysis

importer_exporter_analysis

exporter_cycle_analysis

exporter_keyword_analysis

exporter_role_analysis

exporter_hscode_analysis

exporter_port_analysis

exporter_importer_analysis

使用示例

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

示例 2：按企业名称查询

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

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

示例 5：采购商全维度分析工作流（多工具联动）

开发指南

项目结构

核心模块说明

本地开发

常见问题

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

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

Q: 如何获取 API Key？

Q: 查询有什么限制？

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

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

许可证

贡献

联系方式

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

estore-mcp-server

mcp-comtrade

procureradar-buyer

全球海关贸易数据 MCPofficial

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