Metadata-Version: 2.4
Name: topease-customs-mcp-server
Version: 0.3.1
Summary: MCP server for customs trade data query - 海关贸易数据查询MCP服务
Author: TOPEASE
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.34.2
Description-Content-Type: text/markdown

# topease-customs-data

<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 个国家/地区的进出口贸易数据查询能力。

## 简介

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

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

## 特性

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

## 安装

### 使用 pip

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

### 使用 uv

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

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

```bash
uvx topease-mcp
```

### 从源码安装

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

## 快速开始

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

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

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

或使用 pip 安装的版本：

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

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

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

然后启动服务器：

```bash
uvx topease-mcp --transport streamable-http
```

或使用 Python 模块：

```bash
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条贸易数据
```

大模型将自动调用：

```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
    }
  }'
```

## 开发指南

### 项目结构

```
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](https://tradee.topease.net/) 官网说明。

### Q: 如何获取 API Key？
A: 访问 [https://tradee.topease.net/](https://tradee.topease.net/) 注册账号即可获取。

### Q: 查询有什么限制？
A: API 有请求频率限制，具体限制请查看 API 文档。

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

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