shoplazza-mcp

把 Shoplazza OpenAPI（REST） 封装成 MCP (Model Context Protocol) 服务的 Python 实现， 让 Claude、Cursor、DSH 等支持 MCP 的客户端可以直接读写 Shoplazza 店铺数据 （商品、订单、客户、库存、折扣、订阅 webhook 等）。

端点目录（data/endpoints.json）由 tools/scrape_endpoints.py 从官方文档自动抓取， 覆盖 2026-01 版本共 311 个真实端点、46 个资源组。

---

功能特性

能力	说明
61 个常用端点工具	商品 / 变体 / 订单 / 发货 / 客户 / 地址 / 收藏集 / 折扣 / 优惠券 / 库存 / 门店 / 页面 / 博客 / 文章 / metafield / webhook / 礼品卡 / 供应商 / 数据报表 / 授权 scope 等，输入参数由官方文档自动生成，每个工具描述里标注所需 scope
多店铺支持	一个服务实例可配置多个店铺（SHOPLAZZA_STORES），每个 API 工具带可选 shop_domain 参数按店铺路由；shoplazza_list_shops 查看已配置店铺
官方 CLI 对齐	兼容 CLI 环境变量 SHOPLAZZA_STORE / SHOPLAZZA_UAT；每个 API 工具带 dry_run 参数（CLI --dry-run 同款，只预览请求不发）；call_shoplazza_api 等价 CLI 的 api rest 逃生舱；shoplazza_search_endpoints 等价 schema 自省
311 个端点全覆盖	开启 SHOPLAZZA_REGISTER_ALL_ENDPOINTS=1 后，目录中的每个端点都注册为独立工具
通用透传工具	call_shoplazza_api(method, path, path_params, query, body, dry_run) 可调用任意端点
端点目录工具	shoplazza_search_endpoints / shoplazza_get_endpoint 让模型随时发现正确的端点、参数与所需 scope
双传输方式	stdio（本地客户端默认） / Streamable HTTP（远程服务，--transport http）
稳健性	自动处理「请求头鉴权、统一响应包 {code,message,data}、cursor 分页、429 限流重试（Retry-After，按店铺独立限速）、路径占位符校验、业务错误透出」

---

安装

要求：Python ≥ 3.10，uv（推荐）或 pip。

cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）

不用 uv 时：

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .

配置

通过环境变量提供凭证（不要把密钥写进代码或提交到仓库）：

# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token

变量	必填	默认	说明
SHOPLAZZA_SHOP_DOMAIN	✅*	—	默认/单店铺域名，如 your-store.myshoplazza.com（不带协议）
SHOPLAZZA_ACCESS_TOKEN	✅*	—	默认/单店铺访问令牌，对应 Access-Token 请求头
SHOPLAZZA_STORES	可选	—	多店铺 JSON：{"a.myshoplazza.com":"token-a","b.myshoplazza.com":"token-b"}
SHOPLAZZA_API_VERSION		2026-01	API 版本，如 2025-06、2022-01
SHOPLAZZA_REGISTER_ALL_ENDPOINTS		0	1 时注册全部 311 个端点工具
SHOPLAZZA_MAX_RPS		2.0	客户端每秒最大请求数（漏桶，按店铺独立）
SHOPLAZZA_MAX_RETRY_WAIT		10.0	429 时最多等待秒数
SHOPLAZZA_REQUEST_TIMEOUT		60.0	单请求超时（秒）
SHOPLAZZA_DATA_DIR		包内 data/	自定义端点目录位置

* 单店铺配置 SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN 与多店铺配置 SHOPLAZZA_STORES 二选一即可； 两者都设置时，SHOPLAZZA_SHOP_DOMAIN 为默认店铺。

兼容官方 CLI 的环境变量名（与上表等价，任一即可）：

export SHOPLAZZA_STORE=your-store.myshoplazza.com   # 等价 SHOPLAZZA_SHOP_DOMAIN
export SHOPLAZZA_UAT=your-access-token              # 等价 SHOPLAZZA_ACCESS_TOKEN

也就是说，你在官方 CLI 里用的 SHOPLAZZA_STORE / SHOPLAZZA_UAT 可以直接照搬给本服务， token 同一套。

完整示例见 .env.example。

多店铺用法

配置多个店铺后，服务里的每个 API 工具都会多出一个可选参数 shop_domain：

export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'

• 不带 shop_domain → 走默认店铺（SHOPLAZZA_SHOP_DOMAIN，或 STORES 的第一项）
• 带 shop_domain → 走指定店铺（未知店铺会报错并列出已配置店铺）
• shoplazza_list_shops → 查看服务已配置的所有店铺与默认店铺
• 每个店铺有独立的 Access-Token 与独立限速桶（符合官方按店铺限流的规则）， 多店铺之间互不阻塞

对话示例：

“查一下 US 店铺今天的订单量，再看下 DE 店铺销量 top5 的商品” → 模型会分别以 shop_domain=us.myshoplazza.com 和 shop_domain=de.myshoplazza.com 调用 shoplazza_orders / shoplazza_products

Claude Desktop 配置示例（多店铺）：

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}

需要的 API 权限（scope）

在合作伙伴中心创建/安装应用、或给店铺授权时， 按"最小权限原则"只申请你要用到的 scope。查询数据给 read_*，需要修改才加同名 write_*：

你要访问的数据	申请 scope
店铺信息	read_shop
商品 / 变体 / 库存	read_product
分类 / 收藏	read_collection
订单 / 支付信息	read_order
退款 / 售后	read_order（含售后记录）+ read_data
客户	read_customer
折扣码 / 优惠券 / 价格规则	read_price_rules
礼品卡	read_gift_cards
页面 / 博客 / 文章 / 重定向	read_shop_navigation
评论	read_comments
webhook 管理	需 write_* 对应资源 scope（如 write_product / write_order）
Shoplazza Pay 资金数据	read_finance
数据分析报表	read_data

只读运营场景推荐组合：read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data。 授权后可调用 shoplazza_oauth_access_scopes 工具核对本次安装实际被授予的 scope。 官方完整映射见 访问权限范围。 每个工具的说明里都会标注该端点需要的 scope（如 Required scope: read_order.），403 报错时可以对着排查。

与官方 CLI 的对应关系

官方 Shoplazza CLI 的功能在本服务中都有对应：

官方 CLI	本 MCP	说明
shoplazza products list --params '{"..."}'	shoplazza_products 等 API 工具	同一套端点，输入参数按官方文档自动生成
shoplazza api rest GET /openapi/...	call_shoplazza_api	逃生舱，可调任意端点
--dry-run	每个工具可选 dry_run=true	只预览请求（method/url/query/body/headers，token 打码），不发请求
--format json / --jq	默认返回 JSON 完整响应	结果就是结构化 JSON，可直接消费
shoplazza schema products.list	shoplazza_get_endpoint / shoplazza_search_endpoints	端点、参数、scope 自省
SHOPLAZZA_STORE / SHOPLAZZA_UAT	同名环境变量直接兼容	CLI 的 token 体系与本服务同一套
auth login --scope ...	shoplazza_oauth_access_scopes	授权后核对实际 scope
auth store use（切换活跃店铺）	shop_domain 参数	本服务按调用路由店铺，无需切换全局状态

如何获取 Access Token

• 公开应用：走 OAuth 2.0 Authorization Code 流程， 用 code 换取 access_token（有效期 1 年，可用 refresh_token 刷新）。
• 私有 / 内部集成：在 Shoplazza 后台为应用与店铺生成对应的访问令牌。

运行

stdio（本地 MCP 客户端，默认）

uv run shoplazza-mcp

HTTP（远程服务）

uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765

端点路径默认 /mcp，可用 --http-path 修改。

接入 MCP 客户端

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor：在设置 → MCP 中添加服务器，配置见 examples/mcp-cursor.json。

远程 HTTP（任何客户端）：把 url 指向 http://host:8765/mcp。

也可以直接运行（debug 查看工具列表与 JSON-RPC 交互）：

uv run mcp dev shoplazza-mcp

使用示例（Claude / Cursor 等对话）

• “列出店里最新 10 个订单”
• “查一下商品 abcd-1234 的库存”
• “把订单 order-xxx 取消，原因写 customer requested”
• “新建一个满 100 减 20 的折扣”
• “有什么 API 可以做退款？搜索一下端点” → 模型会调用 shoplazza_search_endpoints("refund") 后自动调用对应端点。

所有响应都返回 API 原始包：{code, message, data, api_call_limit}； 列表类响应在 data 中带 cursor / pre_cursor，配合 page_size / per_page 参数翻页。

开发与维护

• tools/scrape_endpoints.py：从 官方端点文档页 抓取并生成 data/endpoints.json （含每个端点的 method / path / 参数 / 请求体字段 / 响应结构）。
• 曲线维护：新增或移除「常用工具」只需修改 shoplazza_mcp/tools.py 里的 CURATED_SLUGS 清单。
• scripts/smoke_test.py：离线冒烟测试（stdio）；scripts/http_smoke_test.py：HTTP 冒烟测试。

安全说明

• Access Token 请只通过环境变量 / 客户端配置注入，不要写入代码仓库。
• 服务只走 HTTPS（官方要求所有端点仅 HTTPS 访问）。
• 作为 HTTP 服务暴露到外网时，请置于可信内网或自行加鉴权（如网关、防火墙）。

License

MIT