Skip to main content
Glama
topease020

topease-customs-data

by topease020
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid
README.md
# 全球海关贸易数据 MCP

<a href="https://tradee.topease.net/" target="_blank">
  <img src="https://img.shields.io/badge/官网-tradee.topease.net-blue" alt="官网">
</a>
<a href="https://pypi.org/project/topease-mcp/" target="_blank">
  <img src="https://img.shields.io/pypi/v/topease-mcp" alt="PyPI">
</a>
<a href="https://pypi.org/project/topease-mcp/" target="_blank">
  <img src="https://img.shields.io/pypi/pyversions/topease-mcp" alt="Python">
</a>

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

## 简介

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

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

## 特性

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

## 安装

### 使用 pip

```bash
pip install topease-mcp
```

### 使用 uv

```bash
uv add topease-mcp
```

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

```bash
uvx topease-mcp
```

### 从源码安装

```bash
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 客户端的配置文件中添加：

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

或使用 pip 安装的版本：

```json
{
  "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 的客户端中添加配置：

```json
{
  "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>` 请求头传递

## 可用工具

当前共注册 **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`      |

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

## 返回字段说明

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

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

同时包含分页信息：

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

<br />

### 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 条
```

大模型将自动调用：

```json
{
  "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 年从美国的出口记录
```

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

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

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

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

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

```bash
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 采购商，并给出其中最大采购商的采购趋势和供应商构成
```

大模型将依次调用：

```json
// 第 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 基础地址和端口配置

### 本地开发

```bash
# 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](https://tradee.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](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