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 个资源组。

功能特性

Related MCP server: Shopify MCP Server

安装

要求：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 + 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_*：

只读运营场景推荐组合：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 的功能在本服务中都有对应：

如何获取 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