商品大数据服务

该 MCP 服务提供企业关键词搜索、商品搜索、企业商品、海外店铺商品、品牌和电商渠道查询能力，帮助用户开展选品、竞品研究、商品资质核验与渠道分析。

主要功能

• 🏢 企业简称与关键词搜索

• 🔍 零售商品与海外网店搜索

• 🧾 企业零售商品和电商商品查询

• 🌍 海外店铺商品目录查询

• 🏷️ 美业企业品牌与产品功效分析

• 🛒 国内及全球网店渠道分析

Related MCP server: Enterprise Operation Insight MCP Server

服务设计说明

• 服务按实际使用对象提供 6 个 Tool，不按上游 API 数量平铺工具。

• 用户只提供企业简称时，先用 goods_enterprise_search 获取企业全称或稳定 ID。

• 企业商品与海外店铺商品分别提供独立 Tool，避免同一个参数在不同来源中表达不同对象。

• goods_enterprise_products 可选择零售商品或电商商品，但单次调用只访问一个 Product ID。

• 企业零售商品每页最多 10 条；其他翻页查询每页最多 50 条。

• 翻页结果的业务外层统一为 total 与 resultList。

• 已移除依赖第三方商品的店铺热销、月销售和累计销售能力，不再注册价格或销售趋势 Tool。

• Tool 成功时返回 HandaaS Integrator Gateway 提取后的业务 data。

环境要求

• Python 3.10+

• 依赖包：python-dotenv、requests、mcp

本地快速启动

1. 进入项目目录

cd goods-mcp-server

2. 创建虚拟环境并安装依赖

python3 -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env

编辑 .env：

INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30

HANDAAS_REQUEST_TIMEOUT 为可选配置，单位为秒，默认值为 30。

4. 启动服务

python server/mcp_server.py streamable-http

服务默认地址为 http://localhost:8000/mcp。

也可以使用：

./start_mcp_server.sh streamable-http

支持 stdio、sse 和 streamable-http 三种启动方式。

5. Cursor / Cherry Studio 配置

{
  "mcpServers": {
    "goods-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

STDIO 版安装部署

将 {workdir} 替换为项目绝对路径：

{
  "mcpServers": {
    "goods-mcp-server": {
      "command": "{workdir}/mcp_env/bin/python",
      "args": [
        "{workdir}/server/mcp_server.py",
        "stdio"
      ]
    }
  }
}

INTEGRATOR_ID、SECRET_ID 和 SECRET_KEY 需要登录 HandaaS 注册并开通对接器后获取。真实凭据只应保存在本地 .env 或部署密钥中。

可用工具与 Product ID

1. goods_enterprise_search

功能：按企业简称、品牌、产品或其他关键词搜索候选企业。

主要参数：

• matchKeyword（必需）：企业简称或相关关键词。

• pageIndex（可选）：页码，从 1 开始。

• pageSize（可选）：默认 10，最大 50。

返回：候选企业 total/resultList。确认企业后，优先把企业全称、企业 ID 或统一社会信用代码传给企业商品、品牌和渠道 Tool。

2. goods_search

功能：搜索零售商品或海外网店，用于选品、商品发现和跨境渠道筛选。

主要参数：

• matchKeyword（可选）：商品名、网店名或商品关键词。

• source（可选）：retail 零售商品；overseas 海外网店。默认 retail。

• pageIndex（可选）：页码，从 1 开始。

• pageSize（可选）：最大 50；零售搜索默认 10，海外搜索默认 50。

• eshopSource、eshopCategories、eshopSalesLevel（可选）：仅海外网店搜索使用。

• operationStatus、hasAssociateEnterprise（可选）：海外网店状态和关联企业筛选。

返回：total 与 resultList。

3. goods_enterprise_products

功能：按企业查询零售商品或电商商品，适合商品资质核验、企业商品盘点和竞品研究。

主要参数：

• matchKeyword（必需）：企业名称、企业 ID、注册号或统一社会信用代码。

• productType（可选）：retail 企业零售商品；ecommerce 企业电商商品。默认 retail。

• keywordType（可选）：name、nameId、regNumber 或 socialCreditCode。

• pageIndex（可选）：页码，从 1 开始。

• pageSize（可选）：零售商品最大 10、默认 10；电商商品最大 50、默认 50。

零售商品返回字段：

• 商品名称、商品条码、上架日期

• 企业名称、企业 ID

• 品牌名称、GPC 分类

电商商品返回字段：

• 商品名称、图片链接、价格、商品来源

4. goods_overseas_store_products

功能：按海外网店 ID 查询店铺商品目录。

主要参数：

• storeId（必需）：由 goods_search(source=overseas) 返回的网店 _id。

• pageIndex、pageSize（可选）：MCP 本地分页，pageSize 最大 50。

返回：商品数量、评论、BSR、类目、商品名称和链接等信息，并统一为 total/resultList。

5. goods_brand

功能：查询美业企业品牌明细或品牌产品功效概况。

主要参数：

• matchKeyword（必需）：企业标识。

• view（可选）：brand_detail 品牌明细；product_overview 产品功效概况。

• keywordType（可选）：企业标识类型。

6. goods_channel

功能：查询企业国内电商店铺列表或国内外网店全局明细。

主要参数：

• matchKeyword（必需）：企业标识。

• source（可选）：domestic_store 国内电商店铺；global_store 国内外网店。

• keywordType（可选）：企业标识类型。

• pageIndex、pageSize（可选）：仅国内店铺使用，pageSize 最大 50。

使用场景

1. 企业定位：用简称、品牌或产品关键词找到候选企业和稳定标识。

2. 商品发现：按商品关键词发现零售商品，或按商品和平台筛选海外网店。

3. 企业商品盘点：查询企业的零售商品条码、品牌、GPC 分类及电商商品价格。

4. 商品资质核验：使用企业标识定位商品主体，核对商品名称、条码和上架信息。

5. 跨境竞品研究：从海外网店搜索进入指定店铺商品目录，分析类目和 BSR。

6. 品牌分析：了解美业企业品牌、主营产品和产品功效布局。

7. 渠道分析：比较企业国内电商店铺和国内外网店布局。

使用注意事项

1. 单数据源调用：一次调用只访问 source、productType 或 view 选中的一个 Product ID。

2. 分页限制：企业零售商品 pageSize 最大 10；其他翻页工具最大 50。

3. 简称处理：企业简称无法直接查询时，先调用 goods_enterprise_search。

4. 标识优先级：确认候选后，优先使用企业 ID 或统一社会信用代码。

5. 海外店铺 ID：storeId 必须来自海外网店搜索结果，不能使用企业名称代替。

6. 空结果：total=0、resultList=[] 是合法业务结果。

7. 能力边界：本服务不再提供店铺热销、月销售额、累计销量或销售趋势查询。

使用提问示例

goods_enterprise_search

1. “小米”对应哪些企业？

2. 帮我通过“格力”找到准确企业名称和企业 ID。

goods_search

1. 帮我查找零售市场里的咖啡商品，先看 10 条。

2. 搜索销售 coffee 的亚马逊海外网店。

goods_enterprise_products

1. 查询小米科技有限责任公司的零售商品名称、条码和品牌。

2. 查看某企业在电商平台发布的商品名称、价格和来源。

goods_overseas_store_products

1. 查看这个海外网店的商品目录和 BSR。

2. 分页列出指定海外店铺的商品与评论数量。

goods_brand

1. 查询上海家化联合股份有限公司的品牌明细。

2. 分析欧莱雅（中国）有限公司的品牌产品功效概况。

goods_channel

1. 珠海格力电器股份有限公司有哪些国内电商店铺？

2. 北京京东世纪贸易有限公司在国内外有哪些网店渠道？

测试验证

python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -v

单元测试使用 Mock HTTP 响应，不调用真实 HandaaS 商品接口。