shoplazza-mcp

A Python implementation that wraps Shoplazza OpenAPI (REST) into an MCP (Model Context Protocol) service, enabling MCP-capable clients such as Claude, Cursor, and DSH to directly read and write Shoplazza store data (products, orders, customers, inventory, discounts, webhook subscriptions, etc.).

The endpoint catalog (data/endpoints.json) is automatically scraped from the official documentation by tools/scrape_endpoints.py, covering 311 real endpoints and 46 resource groups for version 2026-01.

Features

Installation

Requirements: Python ≥ 3.10, uv (recommended) or pip.

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

Without uv:

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

Configuration

Provide credentials via environment variables (never hardcode secrets into code or commit them to a repository):

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

* Choose either the single-store configuration (SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN) or the multi-store configuration (SHOPLAZZA_STORES); if both are set, SHOPLAZZA_SHOP_DOMAIN is the default store.

See .env.example for a full example.

Multi-store usage

After configuring multiple stores, every API tool in the service gains an optional shop_domain parameter:

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

• Without shop_domain → uses the default store (SHOPLAZZA_SHOP_DOMAIN, or the first entry in STORES).

• With shop_domain → uses the specified store (unknown stores will error and list the configured stores).

• shoplazza_list_shops → view all stores configured in the service and the default store.

• Each store has its own Access-Token and independent rate-limit bucket (in line with the official per-store rate-limiting rules), so multiple stores do not block each other.

Example conversation:

“Check today’s order count for the US store, then look at the top 5 selling products in the DE store.” → The model will call shoplazza_orders / shoplazza_products with shop_domain=us.myshoplazza.com and shop_domain=de.myshoplazza.com respectively.

Claude Desktop configuration example (multi-store):

{
  "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\"}"
      }
    }
  }
}

Required API permissions (scopes)

When creating/installing an app in the Partner Center or authorizing a store, follow the principle of least privilege and only request the scopes you need. Use read_* for reading data; add the corresponding write_* only when you need to modify data:

Recommended combination for read-only operations: read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data. After authorization, you can call the shoplazza_oauth_access_scopes tool to verify the scopes actually granted for this installation. See the official mapping at Access Scopes.

How to get an Access Token

• Public app: Follow the OAuth 2.0 Authorization Code flow and exchange the code for an access_token (valid for 1 year, refreshable with refresh_token).

• Private / internal integration: Generate the corresponding access tokens for the app and store in the Shoplazza admin.

Running

stdio (local MCP client, default)

uv run shoplazza-mcp

HTTP (remote service)

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

The endpoint path defaults to /mcp and can be changed with --http-path.

Connecting to MCP clients

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: Add the server in Settings → MCP; see examples/mcp-cursor.json.

Remote HTTP (any client): Point the url to http://host:8765/mcp.

You can also run it directly (debug to view the tool list and JSON-RPC interaction):

uv run mcp dev shoplazza-mcp

Usage examples (Claude / Cursor conversations)

• “List the latest 10 orders in the store.”

• “Check the inventory of product abcd-1234.”

• “Cancel order order-xxx with reason customer requested.”

• “Create a new discount: 20 off when spending 100.”

• “What APIs are available for refunds? Search the endpoints.” → The model will call shoplazza_search_endpoints("refund") and then automatically call the corresponding endpoint.

All responses return the raw API envelope: {code, message, data, api_call_limit}; list-type responses include cursor / pre_cursor in data, used with page_size / per_page for pagination.

Development and maintenance

• tools/scrape_endpoints.py: scrapes the official endpoint documentation page and generates data/endpoints.json (including each endpoint's method / path / parameters / request body fields / response structure).

• Maintenance: to add or remove “curated tools”, just modify the CURATED_SLUGS list in shoplazza_mcp/tools.py.

• scripts/smoke_test.py: offline smoke test (stdio); scripts/http_smoke_test.py: HTTP smoke test.

Security notes

• Access Tokens should only be injected via environment variables / client configuration; never write them into a code repository.

• The service only uses HTTPS (the official requirement is that all endpoints are HTTPS-only).

• When exposing the service as an HTTP endpoint to the public internet, place it in a trusted internal network or add your own authentication (e.g., gateway, firewall).

License

MIT