horoshop

horoshop-mcp

English: Horoshop の e コマースプラットフォーム向け MCP サーバーです。Claude、Cursor、その他すべての MCP クライアントから、Horoshop ストアの API（注文、カタログ、カテゴリー、顧客、商品セット、参照データ、ウェブフック）に直接アクセスできます。npx -y horoshop-mcp でインストールし、ストアのドメインと管理者ログイン情報を設定します。llms-install.md を使えば、AI エージェントがセットアップ全体を代行できます。MIT ライセンスです。 以下のドキュメントはウクライナ語です。

---

技術的な詳細を含まない、ストアオーナー向けの説明 — ecomkit.com.ua/instrumenty。

これは何ですか

Horoshop 向けの MCP サーバーです。Claude（またはその他の MCP クライアント）から、ストアの API（注文、カタログ、カテゴリー、顧客、商品セット、配送・支払いの参照データ、ウェブフック）に直接アクセスできます。

あとは、自然な言葉で依頼するだけです。

• 「先週の注文のうち、まだ処理中のものを見せて」
• 「カテゴリー「アクセサリー」の商品で、SEO の説明が入力されていないものをエクスポートして」
• 「この20商品の価格を更新して」
• 「8月に登録した顧客は何人？」

サーバーは Horoshop の上に独自のロジックを追加せず、 公式 API の薄いラッパーとして動作します。

必要なもの

• Node.js 20 以降
• Horoshop のストア
• 管理者のログイン情報とパスワード

AI を使ったインストール

最も手早い方法は、アシスタント自身に依頼することです。このプロンプトを Claude Code、 Claude Desktop、または Cursor にコピーしてください。

Встанови мені MCP-сервер horoshop-mcp.
Інструкція для тебе:
https://github.com/ecomkit-com-ua/horoshop-mcp/blob/main/llms-install.md
Прочитай її й виконай: спитай у мене домен магазину, логін і пароль адміна, пропиши конфіг
для того клієнта, у якому ти зараз працюєш, залиш на перший раз режим лише-читання
і перевір, що сервер відповідає.

アシスタントがアクセス情報を尋ね、適切な設定ファイルにブロックを追加して、接続を確認します。 パスワードは設定ファイルにのみ書き込まれ、チャットや git には記録されません。

以下は、手動で設定する場合の手順です。

手順 1. API 用の管理者アカウントを作成する

ストアの管理画面で、設定 → 管理者 → 管理者を追加 を選択します。

個人アカウントは使わず、API 専用の別のアカウントを作成してください。そうすれば、 自分のログインをブロックせずにアクセスをすぐに取り消せます。また、ログでは 連携用のアクセスが行った操作を確認できます。

Horoshop に API キーはありません。認証には通常の管理者ログイン情報とパスワードを使います。

手順 2. サーバーを接続する

Claude Code — プロジェクトのルートにある .mcp.json に設定します。

{
  "mcpServers": {
    "horoshop": {
      "command": "npx",
      "args": ["-y", "horoshop-mcp"],
      "env": {
        "HOROSHOP_DOMAIN": "myshop.com.ua",
        "HOROSHOP_LOGIN": "api",
        "HOROSHOP_PASSWORD": "..."
      }
    }
  }
}

Claude Desktop — 同じ設定を claude_desktop_config.json に記述します （macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。

Cursor — 同じ設定ブロックを ~/.cursor/mcp.json に記述します。

Cline — 同じ設定ブロックを cline_mcp_settings.json に記述します。

Gemini CLI — 同じ設定ブロックを ~/.gemini/settings.json に記述します。

VS Code (GitHub Copilot) — 同じ設定を .vscode/mcp.json に記述しますが、サーバーは mcpServers ではなく servers キーの下に配置します。

stdio 経由で MCP をサポートするその他のクライアントも使用できます。設定はどれも同じです。

設定したら、クライアントを再起動してください。

npx が npm からパッケージを自動でダウンロードするため、別途インストールする必要はありません。リリース前の最新コードは、GitHub から直接インストールできます：["-y", "github:ecomkit-com-ua/horoshop-mcp"]。

設定ファイルには管理者パスワードが平文で含まれます。git の管理対象にしないでください。 .mcp.json を .gitignore に追加してください。

ツール

読み取り：

• horoshop_orders_list — 商品、配送、支払い、割引、UTM タグを含む注文です。 日付、番号、ステータスで絞り込めます
• horoshop_order_statuses — ショップのすべての注文ステータス（Horoshop 4.0+ が必要です）
• horoshop_products_export — カタログの商品：価格、在庫状況、セクション、特性、 在庫数、SEO。セクション、品番、表示状態で絞り込めます
• horoshop_categories_export — カタログのセクションを識別子付きで階層表示します
• horoshop_users_export — 登録済みの購入者
• horoshop_store_reference — ショップの各種情報を1つのツールで取得します：配送方法と配送タイプ、 支払い方法と支払い手段、為替レート付き通貨、商品アイコン、B2B の場合は購入者グループと 価格レベル

書き込み：

• horoshop_products_import — 商品の作成と更新
• horoshop_orders_update — ステータス、支払い済みのフラグ、追跡番号
• horoshop_users_import — 購入者の作成と更新
• horoshop_product_sets_import / horoshop_product_sets_remove — 「まとめ買いでお得」セット
• horoshop_webhook_subscribe / horoshop_webhook_unsubscribe — ショップのイベントの購読

汎用呼び出し：

• horoshop_call — ドキュメントに記載された名前を指定して、任意の API 関数を呼び出します。個別のツールとして まだ用意されていない機能に使います

商品のインポートには注意が必要です

horoshop_products_import は実店舗に書き込みを行い、取り消すことはできません。特に注意すべき デフォルト値：

• images、gallery_common、gallery_360 の override: true はデフォルトで有効です。新しい写真をアップロードする前に 現在のギャラリーが削除されます。削除せずに写真を追加するには override: false を指定してください。ギャラリーに変更を加えない場合は、 ギャラリー自体を指定しないでください
• accessories と gifts は現在のリストに項目を追加するのではなく、置き換えます

一括インポートの前に、テスト用の品番1つで動作を確認し、horoshop_products_export で結果を照合してください。

読み取り専用アクセスが必要な場合は HOROSHOP_READONLY=1 を設定してください。書き込みツールは 一覧に表示されなくなります。

環境変数

必須：

• HOROSHOP_DOMAIN — ショップのドメイン。例：myshop.com.ua。https:// 付きでも、なしでも指定できます
• HOROSHOP_LOGIN — 管理者のログイン名
• HOROSHOP_PASSWORD — 管理者のパスワード

任意：

• HOROSHOP_READONLY=1 — すべての書き込みツールを非表示にします
• HOROSHOP_TIMEOUT_MS — リクエストのタイムアウト。デフォルトは 60000 です
• HOROSHOP_MAX_RESPONSE_BYTES — レスポンスサイズの上限。デフォルトは 100000 です。大きな エクスポートは、表示されたレコード数を示す注記付きで切り詰められます。「大きな エクスポートのページ送り」を参照してください
• HOROSHOP_INSECURE_HTTP=1 — https ではなく http で接続します（テスト用ショップ向け）

大きなエクスポートのページ送り

horoshop_orders_list、horoshop_products_export、horoshop_users_export は limit と offset を受け付けます。ただし、レスポンスサイズには HOROSHOP_MAX_RESPONSE_BYTES による 別の上限もあります。

この2つの上限は独立しているため、重要です。Horoshop が要求された50件の商品をすべて返しても、 レスポンスの容量には、たとえば17件しか収まらない場合があります。残りの33件は取得済みですが、 表示されません。

そのため、次のページへの案内は limit ではなく、表示されたレコード数を基準に計算されます。このように切り詰められたページの後、サーバーは offset 50 ではなく offset 17 から続けるよう案内します。offset 50 を案内すると、 残りの33件が永久に抜け落ち、後続のリクエストでも取得できなくなるためです。

知っておくべき点：

• 切り詰められたページも常に有効な JSON です。レコードは配列の末尾から全体単位で削除され、 サーバーがレコードの途中でレスポンスを切ることはありません
• 予算内にレコードが1件も収まらない場合、サーバーはその旨を明示します。この場合、ページ送りでは解決できません。 要求するフィールドを減らす（include_params）か、HOROSHOP_MAX_RESPONSE_BYTES を引き上げてください
• Horoshop が要求数より少ない件数を返した場合、サーバーはそのページを最終ページとして扱い、 次の offset を提示しません

知っておくべき Horoshop の制限事項

• 認証トークンの有効期間は 600 秒です。サーバーが自動的に更新します
• catalog/export が一度に返す商品は最大 500 件です。offset を使ってページを切り替えてください
• orders/get と users/export は、limit が指定されていない場合 offset を無視します。サーバーは常に両方を送信します
• 1 つのイベントに登録できるウェブフックは最大 5 個で、API では既存のサブスクリプションを表示できません
• 一部の機能には Horoshop 4.0 以降、または B2B モジュールが必要です。その場合、応答に UNDEFINED_FUNCTION が含まれます

開発

npm install
npm run build
node dist/index.js

テスト

npm test

npm test は最初に npm run build を実行するため、テストは常にソースではなくコンパイル済みの dist/ を対象にします。実際のストアは必要ありません。Horoshop のモックはランダムなポート 127.0.0.1 で起動するため、テストで外部へのリクエストは一切発生しません。

各ファイルの内容：

• test/format.test.mjs — 応答フォーマッターのユニットテスト：大きなペイロードの切り詰め、 次のページに関するヒント、EMPTY および WARNING ステータス、エラーの変換
• test/server.test.mjs — 統合テスト。実際の dist/index.js を別プロセスで起動し、 MCP クライアントと同様に stdio 経由で JSON-RPC を使って通信します：ハンドシェイク、 ツール一覧、読み取り専用モード、トークンのライフサイクル、Horoshop の応答形式
• test/support/mock-horoshop.mjs — API モック：認証、期限切れトークン、応答エンベロープ、 変換されない hooks/*、JSON の代わりに HTML を返すケース
• test/support/mcp-client.mjs — テスト用の最小限の MCP クライアント

個別のファイルを実行する場合：

node --test test/format.test.mjs

新しいテストファイルは test/<something>.test.mjs という名前にすれば十分です。npm test が自動的に検出します。 test/support/ 内のファイルはテストではなく、補助コードです。

ライセンス

MIT。

プライバシーポリシー

データは収集されません。 このサーバーにはテレメトリー、分析機能、使用状況レポート機能はなく、 ecomkit が運営するサーバーへのリクエストも行いません。

• 認証情報 — ストアのドメイン、管理者のログイン名、パスワードは、お使いのマシン上にある、ご自身の MCP クライアントの設定ファイルに保存され、ご自身のストアにのみ送信されます。 作成者がこれらにアクセスすることはありません。
• データの送信先 — サーバーはストアのデータを AI アシスタントとの会話に渡すため、 このポリシーではなく、AI プロバイダー（Anthropic、Google、OpenAI など）のプライバシーポリシーに従って データが送信されます。社外に持ち出してはならないデータのエクスポートは依頼しないでください。
• 第三者 — 上記の 2 者以外にはありません。共有、販売、譲渡は一切行いません。
• 保持 — 作成者は何も受信しないため、データを保持しません。
• お問い合わせ — [email protected]

ポリシー全文（ウクライナ語および英語）： ecomkit.com.ua/pryvatnist-instrumenty

---

Сергій Троїцький が作成しました — オンラインストアの立ち上げ、SEO、業務自動化を支援します。 Horoshop ストアの監査をご希望ですか？ ecomkit.com.ua