sellercloud-mcp

SellerCloud初のModel Context Protocolサーバー。Claudeをカタログ、在庫、注文、チャネルリスティングに接続し、5分で読み取り専用の連携を実現します。

このプロジェクトの目的

SellerCloudには公開SDKがありません。REST APIは十分に文書化されていますが、ブランド化されておらず、自動化を行うチームは毎回同じ認証やページネーションの処理をゼロから記述することになります。

Claude（またはMCP対応のAIアシスタント）を日常的なEC業務に使用する場合、このギャップが「今日の注文を要約して」がすぐに使えるか、カスタム統合が必要になるかの分かれ目となります。

sellercloud-mcpはこのギャップを埋めます。これは、7つの読み取り専用SellerCloudエンドポイントをMCPクライアントに公開する、軽量でテスト済みのMITライセンスMCPサーバーです。長年にわたるEC自動化の経験に基づいて構築されています。

Related MCP server: Amazon Marketplace MCP Server by CData

できること

このサーバーをClaude Code、Claude Desktop、または任意のMCPホストに接続し、以下のような質問を投げかけることができます：

• 「WIDGETを含むSKUを検索して、在庫レベルを表示して。」

• 「昨日、すべてのマーケットプレイスで何件の注文が出荷されましたか？チャネルごとにグループ化して。」

• 「注文番号100001を取得して、どの明細が出荷されたか教えて。」

• 「会社ID 9001に設定されているチャネルを一覧表示し、どれがアクティブか教えて。」

• 「SKU ACME-001について、すべてのチャネルリスティングの価格を比較して。」

Claudeが直接カタログを読み取ります。コピー＆ペーストやスプレッドシート、カスタムパイプラインは不要です。

ツール (v0.1, すべて読み取り専用)

書き込みエンドポイント（注文作成、在庫更新、チャネル変更のプッシュ）は、意図的にv0.1には含まれていません。読み取り専用の操作性が安定した後、v0.2で計画されています。

インストール

pip install sellercloud-mcp

v0.1はこのリポジトリから提供されます。PyPIへの公開は保留中です。現時点では pip install git+https://github.com/alveyautomation/sellercloud-mcp でインストールするか、クローンしてローカルで pip install -e . を実行してください。

認証情報の構成

サーバーは環境変数からすべてを読み取ります。.env.example を .env にコピーし、テナント情報を入力してください：

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

読み取り専用のSellerCloudアカウントを使用してください。 v0.1は GET エンドポイントのみを呼び出しますが、防御的プログラミングの観点から、何も変更できない専用ユーザーをサーバーに割り当てるべきです。書き込みツールを備えたv0.2がリリースされたら、その時に権限をアップグレードしてください。逆の順序で行わないでください。

Claude Codeへの接続

~/.claude/claude_code_config.json（またはプロジェクトのMCP設定）に追加します：

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

Claude Codeを再起動します。新しいセッションで7つの sellercloud_* ツールが表示されます。

Claude Desktopへの接続

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または %APPDATA%\Claude\claude_desktop_config.json (Windows) を編集し、上記と同じ mcpServers ブロックを追加します。デスクトップアプリを再起動してください。

ツールリファレンス

すべてのツールはJSONエンベロープを返します：

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

レスポンス例：

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

カタログレコードを返します。SKUが会社のカタログに存在しない場合は data: null を返します。

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

ページネーションは透過的に処理されます。SellerCloudのページサイズ上限は50ですが、ツールは limit までページを収集します。limit を超える注文があった場合、レスポンスには limit_reached: true が含まれます。

sellercloud_get_order

sellercloud_get_order(order_id: int)

完全な注文レコード（Items[]を含む）を返します。404の場合は data: null を返します。

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

返されるレコードには以下が含まれます：

• InventoryAvailableQty — APIが現在販売可能とみなす数量

• PhysicalQty — 手持ち数量

• ReservedQty — 未処理の注文のために確保されている数量

• OnOrder — 入荷予定数量

「販売可能な数量」としては InventoryAvailableQty を使用してください。

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

会社に設定されているチャネルフィードのリストを返します。各レコードには ChannelID、Name、Active が含まれます。

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

チャネルごとのリスティング詳細。マーケットプレイス間の価格をスポットチェックするのに便利です。

ローカル開発

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

プリコミットフック（gitleaks、ruff、フォーマッタ、テナントフィンガープリントスクラバー）：

pip install pre-commit
pre-commit install

実際のSellerCloudサンドボックスアカウントに対する統合テストは SELLERCLOUD_INTEGRATION_TESTS=1 で制御されます。通常のコントリビューションには必須ではありません。

トラブルシューティング

Failed to obtain SellerCloud token — ユーザー名/パスワードが拒否されました。最も一般的な原因：アカウントで2FAが有効になっているか、ロックアウトされています。SellerCloudの POST /api/token エンドポイントは2FAなしのサービスアカウントを想定しています。

Missing required environment variables — .env が読み込まれる前にサーバーが起動しようとしました。親シェルで変数をエクスポートするか、MCPホストの設定の env ブロックにそれらが含まれていることを確認してください。

データがあるはずなのに結果が空 — company_id が正しいか確認してください。SellerCloudは、companyID を明示的に渡さない限り、認証されたユーザーのデフォルト会社のみを返します。

ページネーションが遅い — ページサイズは弊社ではなくSellerCloudによって50に制限されています。大きな日付範囲を指定する場合、複数回の往復が発生することを想定してください。

コントリビューション

Issueやプルリクエストを歓迎します。以下の点にご注意ください：

• PRを開く前に pytest を実行してください (pip install -e ".[dev]")。

• pre-commit run --all-files を実行してください。

• v0.1の範囲内では読み取り専用の追加に留めてください。書き込みエンドポイントはv0.2で追加されます。

• テストには合成データのみを使用してください。実際のSKU、顧客名、注文番号は使用しないでください。

ライセンス

MIT — LICENSE を参照してください。

免責事項

sellercloud-mcp は非公式のサードパーティ統合です。SellerCloud, Inc.によって承認、提携、サポートされているものではありません。 「SellerCloud」はSellerCloud, Inc.の商標です。自己責任で使用し、本番環境での意思決定に使用する前に、テナントに対して動作を確認してください。