mcp-shopee

@codespar/mcp-shopee

适用于 Shopee 的 MCP 服务——Shopee Open Platform Partner API v2。

Shopee 是 LatAm 商家在线 GMV 主要集中的两个电商平台之一（在巴西占据主导地位，并在整个区域快速扩张）。搭配 @codespar/mcp-mercadolibre 使用，此软件包可让 Agent 全面覆盖 LatAm 的主要电商平台——每个平台都有自己的卖家生态，因此商家通常会同时经营这两个平台。

工具（22 个）

工具	用途
get_shop_info	获取已授权 Shopee 店铺的基本信息（shop_name、region、status、授权到期时间）。
list_orders	列出指定时间范围内的订单，可选择按 order_status 筛选。
get_order_detail	根据 order_sn 获取一个或多个订单的完整详情（以逗号分隔，最多 50 个）。
ship_order	为订单安排发货——根据……选择请求揽件、送至投递点或提供物流单号。
cancel_order	取消尚未发货的订单。
list_products	列出店铺中的商品，可选择按状态筛选。
get_product_detail	根据 item_id 获取最多 50 件商品的详细基本信息。
update_product_stock	更新商品（或其型号／变体）的库存。
update_product_price	更新商品（或其型号／变体）的价格。
get_shipment_list	列出当前正在配送的订单（状态为 SHIPPED 或运输中）。
get_return_list	列出店铺的退货／退款申请，可选择按状态和时间范围筛选。
confirm_return	根据 return_sn 确认（接受）买家发起的退货申请。
add_item	在店铺中创建新商品。
update_item	更新现有商品。
delete_item	根据 item_id 从店铺中删除商品。
get_shipping_parameter	在调用 ship_order 前，获取订单所需的发货参数。
get_tracking_number	获取已发货订单的物流单号（以及可用时的承运商信息）。
download_shipping_document	请求下载一个或多个订单的运输标签／航空运单 PDF。
accept_return_offer	接受买家的退货提议（建议方案），针对 return_sn 结束协商，让买家获得满意结果。
add_discount	创建带有时间范围的店铺级折扣（促销）。
add_bundle_deal	创建捆绑销售促销（例如，
send_chat_message	在 Shopee 卖家聊天中向买家发送文本或贴纸消息。

安装

npm install @codespar/mcp-shopee@alpha

环境变量

SHOPEE_PARTNER_ID="2001234"        # partner_id (integer) from Shopee Open Platform
SHOPEE_PARTNER_KEY="..."           # partner_key (secret) for HMAC signing
SHOPEE_ACCESS_TOKEN="..."          # merchant access_token (4h lifetime; refresh via refresh_token)
SHOPEE_SHOP_ID="123456789"         # shop_id (integer) from authorization flow
SHOPEE_ENV="production"            # or "sandbox"

身份验证

Shopee 使用合作伙伴签名请求。对于店铺级端点，签名格式如下：

base_string = partner_id + api_path + timestamp + access_token + shop_id
sign        = hex(HMAC_SHA256(partner_key, base_string))

每次请求都会将 partner_id、timestamp、access_token、shop_id 和 sign 作为 URL 查询参数附加。签名辅助函数（src/index.ts）会在每次调用时处理此操作。

access_token 通过 Shopee Open Platform 上的商家授权 OAuth 流程获取，有效期为 4 小时。使用 refresh_token（有效期为 30 天）刷新——此交换流程不在本 MCP 的范围内，通常由单独的令牌管理服务处理。

运行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-shopee

# HTTP (server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-shopee

基础 URL

• 生产环境：https://partner.shopeemobile.com/api/v2
• 沙盒环境：https://partner.test-stable.shopeemobile.com/api/v2

通过 SHOPEE_ENV 选择。

状态

0.1.0-alpha.1 — Shopee 的 Partner API 文档门户要求开发者注册，因此部分端点载荷和字段级约定（尤其是 ship_order 的揽件／投递点对象及物流渠道细节）应在投入生产使用前对照在线文档进行验证。签名方式和基础 URL 选择已按规范实现。

企业版

需要针对 Agent 支付进行治理、预算限制和审计跟踪？CodeSpar Enterprise 可在这些 MCP 服务之上提供策略引擎、支付路由和合规模板。

许可证

MIT