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 のリソースグループをカバーしています。

機能

インストール

要件: 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 がデフォルトストアになります。

完全な例は .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 ストアの売上トップ 5 の商品も見て” → モデルは 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 を確認できます。 公式の完全なマッピングは アクセス権限スコープ を参照してください。

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 / パラメータ / リクエストボディフィールド / レスポンス構造を含む）。

• Curated メンテナンス：「よく使うツール」の追加・削除は、shoplazza_mcp/tools.py 内の CURATED_SLUGS リストを変更するだけです。

• scripts/smoke_test.py：オフラインのスモークテスト（stdio）；scripts/http_smoke_test.py：HTTP スモークテスト。

セキュリティに関する注意

• Access Token は環境変数 / クライアント設定経由でのみ注入し、コードリポジトリに書き込まないでください。

• サービスは HTTPS のみを使用します（公式では全エンドポイントが HTTPS のみのアクセスを要求しています）。

• HTTP サービスとして外部ネットワークに公開する場合は、信頼できる内部ネットワークに配置するか、独自に認証（ゲートウェイやファイアウォールなど）を追加してください。

ライセンス

MIT