mcp-yshop

Yahoo!ショッピングの公式APIを操作する、TypeScript・stdio方式のローカルMCPサーバーです。

公開リポジトリ: ak1tnk/mcp-yshop-public。開発用の非公開コピーからは、公開側との同期手順に従って検査済みソースをPRとして送れます。

公開前・運営中の認証情報と個人情報の混入防止にはコミット前・push前チェックの設定を使用してください。Windowsでの追加チェックの依頼手順も含みます。

2026-11-04時点の公式一覧にある現行104エンドポイントに対応しています。注文・定期購入・商品・在庫・画像・SHPカテゴリ/ブランド・ストアカテゴリ・出品管理・デザイン・問い合わせ・店舗在庫・公開情報を含みます。公式仕様へのリンク付き対応表

初回セットアップ（AWS不要）

Node.js 22.19以降のLTS（推奨24）を用意し、取得したリポジトリ内で実行します。

git clone https://github.com/ak1tnk/mcp-yshop-public.git
cd mcp-yshop-public
npm ci
npm run setup

セットアップではストアアカウント、Yahoo!デベロッパーネットワークで発行したサーバーサイドアプリのClient ID / Client Secretを入力します。自分のアプリについて、利用するショッピングAPIの利用申請とストア管理者の権限を準備してください。公式の導入手順

認可方法は次から選べます。

• browser：表示されたYahoo! JAPAN公式URLをブラウザで開き、ストア管理者のIDで同意します。アプリに登録済みのコールバックURLを正確に入力し、遷移後のURL全体をターミナルへ貼り付けます。MCPはランダムなstateと戻り先を照合してから認可コードを交換します。コールバック先は自分で管理するURLを使ってください。ローカルURLを登録していてページが開けない場合も、アドレス欄の遷移後URLを使用できます。
• existing：すでに取得したRefresh Tokenを非表示で入力します。

認証値と認可結果URLの入力は非表示です。ブラウザ用の認可URLには公開識別子のClient IDが含まれます。認証値をチャット・コマンド引数・リポジトリへ記載しないでください。セットアップはSSMへアクセスしません。再認可もnpm run setupで行い、MCPを再起動します。ブラウザでの認可は利用者が行い、自動ログインは行いません。公式の認可フロー・コード交換

ローカル設定はプロジェクトの外へ保存します。

保存内容は暗号化されていません。macOS / Linuxはファイル権限600、新規ディレクトリ700を使用します。Windowsでは専用ユーザーのAppDataに保存し、共有アカウントで使う場合は所有者だけがアクセスできるACLを設定してください。プロジェクト内への保存やシンボリックリンク経由の読み込みは拒否します。.envは読み込みません。

署名用公開鍵とバージョン、Proxy URLは任意です。公開鍵はストアクリエイターProで発行された値を使い、改行を\nにした文字列として入力します。バージョン番号を固定値で流用しないでください。 公開鍵なしでもYahoo! ID認証を使用できますが、注文などのAPIでは再認可までの期間が短くなります。公開鍵の有効期限とYahoo!側での再認可は別途管理してください。公開鍵認証の公式説明

MCPクライアントへの登録

セットアップ後、Claude Desktopなどのstdioクライアントへ以下を登録します。argsは自分が取得したディレクトリの絶対パスに置き換えてください。nodeがクライアントのPATHにない場合はNode.js本体の絶対パスを使います。

{
  "mcpServers": {
    "yshop": {
      "command": "node",
      "args": ["/absolute/path/mcp-yshop-public/dist/index.js"],
      "env": { "YSHOP_AUTH_SOURCE": "local" }
    }
  }
}

ローカルプラグイン向けのplugin.jsonと${PLUGIN_ROOT}を使うmcp.jsonも同梱しています。インストールとビルド後に使用します。実行時に他のローカルプロジェクトへ依存しません。

codex mcp add yshop --env YSHOP_AUTH_SOURCE=local -- node /absolute/path/mcp-yshop-public/dist/index.js

npm startは標準入力でMCPメッセージを待ちます。通常はMCPクライアントから起動します。stdoutはMCPプロトコル専用です。

認証元と設定

YSHOP_AUTH_SOURCEでlocal / env / ssmを選びます。未指定の場合は認証用環境変数が一つでもあればenv、ストアIDのみ指定されていれば既存構成向けにssm、それ以外はlocalを使います。不完全な認証を別の認証元で補うことはありません。ストアIDの個人用既定値はありません。

ProxyはYahoo! ID認証と全APIの通信に適用します。注文APIなど接続元IPの登録が必要なAPIでは、自分の固定IPまたはProxyの出口IPをYahoo!側へ登録してください。公式共通エラー一覧

AWS SSMを使う場合

従来のSSM認証も利用できます。認証値は実行時に復号してメモリ上で使い、ローカル設定へ書き出しません。AWSのアクセスキーをコードやMCP設定に記載せず、既存のAWS認証経路を利用してください。

SSMのProxyオブジェクトは先頭ホストを使い、リクエストごとに出口IPを変更しません。追加項目は使いません。必要な権限は対象パラメータへのssm:GetParameterと、カスタムKMSキー使用時のkms:Decryptです。SSMへの書き込み権限は不要です。

SSM用MCP設定のenvには、認証値を含めず次の項目を指定します。ストアIDと署名バージョンは自分の設定へ置き換えてください。

{
  "YSHOP_AUTH_SOURCE": "ssm",
  "AWS_REGION": "ap-northeast-1",
  "YSHOP_SELLER_ID": "example-store",
  "YSHOP_SIGNATURE_VERSION": "1",
  "YSHOP_USE_PROXY": "true"
}

0.2から更新する場合は、MCPクライアント側にYSHOP_SIGNATURE_VERSIONと必要なYSHOP_USE_PROXY=trueを明示してください。公開鍵バージョンとストアIDをコードの既定値から取り除いています。SSM・環境変数・ローカル設定を更新したらMCPを再起動します。

ツール

全API向けの共通ツール3個と、従来の補助ツール15個を提供します。APIごとの固定URL・HTTPメソッド・XML/JSON/form・ストアIDの位置はサーバー側で管理します。

共通ツールでは公式のパラメータ名をそのまま渡します。parametersはXMLならReqの内側、JSONなら本文、GET/formならフラットなパラメータです。queryで本文とは別のURLクエリ、path_parametersでURL内の{subscription_id}などを指定できます。seller_id・sellerId・SellerId・appid・署名は選択した認証元とストア設定から自動設定します。任意のURLや認証ヘッダーは指定できません。公開情報APIのストア検索条件は他ストアも指定できます。

注文ステータス変更のドライラン例（yshop_write_api）：

{
  "operation": "orderStatusChange",
  "parameters": {
    "Target": { "OrderId": "example-store-10000000", "IsPointFix": false },
    "Order": { "OrderStatus": 4, "CancelReason": 210 }
  }
}

実行時は対象注文とキャンセル理由を確認し、依頼された操作にだけdry_run=falseを指定します。注文完了と出荷変更は公式仕様に従ってIsPointFix=trueを明示します。問い合わせ送信・添付ファイル投稿・注文変更・公開も同じドライランの対象です。

CSV・画像ZIP・問い合わせ添付の送信にはuploadを使用します。CSVの文字コードは変換せず保持します。画像ZIPは含まれる画像名・形式・展開サイズ、PDFは暗号化の有無を送信前に確認します。

{
  "operation": "uploadItemFile",
  "parameters": { "type": 1 },
  "upload": { "path": "/absolute/path/products.csv" }
}

ダウンロードAPIはyshop_read_apiで実行すると、このプロジェクトのout/へ保存し、パス・サイズ・SHA-256を返します。データの文字コードとバイナリは保持します。サーバーのファイル名はローカル保存先に使用せず、生成した名前で保存します。取得上限は256MB、アップロードは25MB（単体画像は2MB）、画像ZIPの展開合計は250MBです。ファイル転送のタイムアウトは120秒なので、大きいファイルを扱うクライアントではツールの実行時間も合わせて設定してください。

JSON配列を返すAPIはdata.resultsに配列を格納します。データチェック履歴のErrorCodeは検証結果のデータとして返し、呼び出し自体のAPIエラーと区別します。

既存の補助ツールは以下のとおりです。

全更新ツールはdry_run=trueが既定です。まず送信内容を確認し、依頼された変更にdry_run=falseを指定すると送信します。ドライランはSSM取得・Yahoo API通信を行いません。画像のドライランでは指定画像の形式・サイズを検証し、SHA-256を返します。

価格変更の確認例：

{
  "items": [{ "item_code": "example-shirt", "price": 5900, "sale_price": "" }]
}

yshop_update_itemsはpriceとsale_priceの同時指定が必要です。特価を維持する場合は、先に取得した現在の特価を渡してください。特価を設定しない場合は空文字を明示します。省略した他の項目は変更しません。部分更新の公式仕様

yshop_edit_itemは全体保存です。省略した項目はデフォルト値に上書きされます。 既存商品の説明・バリエーション等を保つ場合は、それらを含む完全なfieldsが必要です。name・path・product_category・priceを必須とし、追加の商品項目は公式のパラメータ名で渡せます。全体保存の公式仕様

在庫は商品コード:個別商品コード形式にも対応します。補助ツールyshop_set_stockは絶対数を受け付けます。共通ツールのsetStockでは加算・減算・超過購入設定・在庫クローズ解除も公式パラメータで指定できます。存在しないコードにも在庫が作成されるため、更新前に対象コードを確認してください。Quantityが空文字の参照結果は無限在庫です。在庫更新の公式仕様

商品保存と公開は別操作です。全反映予約はストア全体の保留変更が対象なので、先にyshop_list_publish_historyのpublish_id=0で内容を確認します。公開APIの正常応答も受付を示すため、完了は反映履歴で確認します。追加画像はアップロード時に本番反映される場合があります。個別反映・全反映予約・追加画像

出荷変更は公式要件に従いIsPointFix=trueを送信します。ポイント確定や、支払い方法によっては売上確定を伴います。出荷済みへの変更には出荷日を指定してください。APIの警告も応答に含めて返します。出荷変更の公式仕様

API呼び出しは1プロセス内で直列に実行し、前の完了から1秒空けます。複数MCPプロセスや既存スクリプトを同時実行した場合の制限は共有しないため、同じストアの操作は並行起動しないでください。HTTP 200内のNG・エラー、在庫のHTTP 207も失敗として扱います。更新APIは自動再送しません。通信結果が不明な場合は対象状態を参照してから判断してください。

検証

npm run build
npm run check
npm run smoke

# 設定した認証元と公式APIの参照操作だけを実接続で確認
npm run smoke -- --live --orders

通常のテスト・smokeは外部サービスへ接続しません。実接続smokeでも更新ツールはドライランだけです。認証値・Proxy値・購入者情報・APIレスポンス本文を検証ログへ出力しません。GitHub ActionsもAWS認証なしでビルドとテストを実行します。

ローカルテストでは104操作すべての通信形式・URL・ストア認証の付与と、更新APIを参照ツールから実行できないことを確認します。本番で全更新APIを実行したという意味ではありません。契約・利用申請・ビジネスID権限によって実際に使用できるAPIは異なります。公式本文とサンプルの不一致は対応表へ記録しています。提供終了済みの商品検索V1・おすすめ情報モジュール・商品レビュー検索は対象外です。

認証ファイル・秘密鍵・.env・ローカルログ・依存パッケージ・ビルド生成物は.gitignoreで追跡から除外しています。package.jsonはprivate: trueでnpm公開を無効にしています。