Ebay Mcp

eBay MCP サーバー — Claude、Cursor、あらゆる AI アシスタントに eBay Sell API へのフルアクセスを提供します。在庫、注文、マーケティング、分析に対応する 379 個のツールを、お客様自身のキーを使ってローカルで実行できます。

_{非公式のオープンソースプロジェクトです。eBay Inc. との提携、認可、推奨を受けていません。}

eBay MCP は、AI アシスタント — Claude Desktop、Claude Code、Cursor、Cline、Windsurf、Zed、Continue.dev、Roo Code、Amazon Q Developer — を**eBay Sell APIに直接接続する、ローカルのModel Context Protocolサーバーです。在庫管理、注文処理、プロモーテッドリスティングのマーケティング、分析、開発者向けツールに対応する379 個のツールを提供し、対象としているeBay Sell、Commerce、Developer API の 100%**（356 個の固有エンドポイント）をカバーします。すべて STDIO またはローカル HTTP 経由でお使いのマシン上で実行され、クラウド中継は不要です。また、eBay の認証情報がお使いのコンピューターから外部に送信されることはありません。

**免責事項：**非公式のサードパーティプロジェクトであり、**eBay Inc. との提携や推奨を受けていません。**保証なしの「現状有姿」で提供されます。eBay API ライセンス契約およびデータ取り扱い要件の遵守、認証情報の安全な管理、レート制限の遵守は、お客様の責任です。本番環境で使用する前に、サンドボックスでテストしてください。LICENSEをご覧ください。

目次

• 機能
• 機能マップ
• eBay MCP と eBay API そのものの比較
• ワンクリック AI セットアップ
• クイックスタート
• デモ
• 設定
• 利用可能なツール
• インタラクティブ UI（MCP Apps）— ベータ版
• 使用例
• 対象範囲と安全性
• ログとトラブルシューティング
• FAQ
• コントリビューション
• リソース
• ライセンス
• コントリビューター

機能

• eBay API ツール 379 個 — 在庫、注文、マーケティング、分析、メタデータ、分類、開発者向けツールを含む、eBay Sell API を 100% カバーしています。
• AI クライアント 9 種類を自動設定 — Claude Desktop、Cursor、Zed、Cline、Continue.dev、Windsurf、Roo Code、Claude Code CLI、Amazon Q Developer。
• OAuth 2.0 を組み込み — ユーザートークンを包括的に管理し、自動更新に対応します。また、ユーザートークン（1 日あたり 10,000〜50,000 リクエスト）からクライアント認証情報（1 日あたり 1,000 リクエスト）へスマートにフォールバックします。
• デフォルトで高い耐障害性 — 429 レート制限時に指数バックオフで自動再試行し、エラーを一貫して明確に通知します。
• 型安全 — TypeScript をエンドツーエンドで使用し、Zod でツール入力を検証し、OpenAPI から型を生成しています。
• ローカル優先でプライバシーを保護 — STDIO またはローカル HTTP 経由で動作します。認証情報やデータがお使いのマシンから外部に送信されることはありません。
• サンドボックスと本番環境 — 1 つの変数で環境を切り替えられます。
• 1 コマンドでセットアップ — npm run setup で認証情報、OAuth、MCP クライアントを設定し、OAuth フローのためにブラウザーを自動的に開きます。
• 十分なテスト — GitHub Actions を通じて、変更のたびに CI で 1,000 件以上の自動テストを実行します。

機能マップ

公開するツールファミリーを選ぶときや、アシスタントに何ができるかを尋ねるときは、このマップを使用してください。ファミリー名は EBAY_MCP_TOOLS と一致するため、すべてのツールを使用することも、動的に検出することも、特定のワークフローに必要なファミリーだけを使用することもできます。

出品前の確認：必須の商品属性

ebay_create_or_replace_inventory_item、ebay_create_offer、または ebay_get_listing_fees を呼び出す前に、選択したカテゴリの最新の要件を取得してください。

ebay_get_default_category_tree_id → ebay_get_category_suggestions → ebay_get_item_aspects_for_category

商品属性のレスポンスには、必須および推奨の商品属性が示されます。オファーを作成する前に、必須の商品属性をすべて在庫商品に設定してください。要件はカテゴリやマーケットプレイスによって異なるため、いずれかが変更された場合は検索をやり直してください。例や固定のグローバルな代替値に頼らないでください。

オークション出品

ebay_create_offer、ebay_update_offer、ebay_bulk_create_offer は、同じ Inventory モデルを使って両方の出品形式を受け付けます。

カテゴリーで許可されている形式と期間は ebay_get_listing_type_policies で確認し、その後 ebay_publish_offer の前に ebay_get_listing_fees を実行してください。2 つの形式が混在したリクエスト本文は、eBay にリクエストが送信される前にローカルで拒否されます。

Trading（XML）経由のオークション

レガシーツールでは、同じ切り替え指定をトップレベルの format 引数で受け取ります（デフォルトは FIXED_PRICE）。format: "AUCTION" を指定した ebay_create_listing、ebay_revise_listing、ebay_end_listing、ebay_relist_item は、*FixedPriceItem 系ではなくオークション対応の呼び出し（AddItem、ReviseItem、EndItem、RelistItem）を使用します。また、ebay_create_listing は Item に ListingType: "Chinese" を追加します。

形式が混在したペイロードはローカルで拒否されます。既存商品の形式が不明な場合は、まず ebay_get_listing で ListingType を読み取ってください（Chinese = オークション）。

ローカルファイルからの写真と動画

オファーを公開するには、少なくとも 1 枚の写真が必要です。メディアツールは、eBay の Media API を通じてローカルファイルをアップロードし、Inventory API に必要な情報を返します。

ローカルファイルへのアクセスは、許可するまで無効です。EBAY_MCP_MEDIA_DIRS（パス区切りのディレクトリ）および／または EBAY_MCP_MEDIA_ROOT（media://<relative-path> の参照も解決する単一のディレクトリ）を設定してください。包含チェックの前にシンボリックリンクを解決します。許可されたディレクトリの外にあるファイルは、アップロード前に拒否されます。対応形式：最大 12 MB の JPG、PNG、GIF、BMP、TIFF、WEBP、AVIF、HEIC、および最大 150 MB の MP4/MOV。未使用のアップロードは eBay 側で期限切れになります。出品で使用されると永続化されます。

画像 URL とドキュメント

これら 8 つのツールも inventory ファミリーに含まれます。

出品用マニュアルの場合は、ebay_create_document を {"documentType":"USER_GUIDE_OR_MANUAL","languages":["ENGLISH"]} で呼び出し、 返された documentId と "path":"media://manual.pdf" を指定して ebay_upload_document を呼び出します。代わりに、同じメタデータと "documentUrl":"https://example.com/manual.pdf" を指定して ebay_create_document_from_url を呼び出すこともできます。 出品に ID を関連付ける前に、ebay_get_document を使ってステータスが ACCEPTED であることを確認してください。これらの呼び出しには、読み取りも含め、 sell.inventory に対するユーザーの同意が必要です。

出品ドキュメントで受け付けられる形式は PDF、JPEG/JPG、PNG で、サイズ上限は **10 MiB（10,485,760 バイト）**です。注文後ドキュメントでは BMP と GIF も受け付けられ、 サイズ上限は **5 MiB（5,242,880 バイト）**です。ローカルファイルのアップロードでは、 上記と同じメディア形式の許可リストが適用され、拡張子とファイルシグネチャが確認されます。 アニメーション PNG および複数ページの PNG はサポートされていません。複数ページの コンテンツには PDF を使用してください。PDF のページ数上限は、eBay によって用途ごとに 定められています。

返品ラベルの場合は、 {"path":"media://label.pdf","documentUsageType":"RETURN_SHIPPING_LABEL","entityType":"RETURNS","entityId":"YOUR_RETURN_ID"} を指定して ebay_upload_post_order_document を 呼び出します。初期状態は SUBMITTED です。公開するには、これらのツールの対象外である 別途の eBay GraphQL ミューテーションが必要です。送信済みドキュメントのダウンロードは所有者のみ可能です。公開済みドキュメントのダウンロードには、注文後のフローで認可が必要です。公開済みドキュメントは削除できず、期限切れのドキュメントは利用できません。

注文後ツールを利用するには、適格なキーセットと https://api.ebay.com/oauth/api_scope/commerce.post_order.document に対するユーザーの同意が必要です。 このスコープを既存の EBAY_OAUTH_SCOPES リストに追加し、OAuth の設定と同意を再度行ってください。 この変数はリクエストするスコープのリストを置き換えるため、必要な他のスコープも残してください。 トークンを更新しても、追加のスコープは付与されません。このスコープは認識されますが、デフォルトの同意リクエストには追加されません。すべての Media API POST 操作には、ユーザーレベルで 5 秒あたり 50 リクエストという eBay の制限が適用されます。レート制限エラーは呼び出し元に返されます。

eBay の Media API の概要 とリリースノートを参照してください。

財務、フィード、ストア、配送ラベル

これらのファミリーでは、Sell API の残りの分野である Finances、Feed、Stores、Logistics、Account v2 に加え、これまで不足していた Metadata の配送、Taxonomy、Charity の各エンドポイントを網羅します。

非同期の変更。 Feed タスクとストアカテゴリの変更では、eBay の Location ヘッダーから読み取った taskId が返されます（Feed のスケジュールでは scheduleId が返されます）。タスクが完了するまで ebay_get_feed_task または ebay_get_store_task をポーリングしてから、結果ファイルを取得してください。eBay では、同時に進行できるストアカテゴリの変更は1件までです。

ファイルの入出力。 ダウンロード（Feed の入力ファイル、結果ファイル、スケジュールファイル、配送ラベル、Taxonomy の属性エクスポート）は、バイト列を Base64 で格納した埋め込み MCP リソースとして返されます。ディスクには何も書き込まれません。ファイルサイズが判明した時点で 25 MiB を超えている場合、残りを読み込まずにエラーになります。EBAY_US などの大規模なマーケットプレイスでは属性エクスポートがこの制限を超えるため、そこで各カテゴリに対して ebay_get_item_aspects_for_category を使用してください。ebay_upload_feed_task_file は、メディアツールと同じ EBAY_MCP_MEDIA_DIRS / EBAY_MCP_MEDIA_ROOT の許可リストを通じて、最大15 MiB（eBay のデータファイル制限）のローカル .xml、.csv、.zip、または .gz ファイルを読み込みます。

資金の移動。 ebay_create_shipment_from_shipping_quote は郵便料金を購入し、出品者の請求契約に請求します。ebay_cancel_shipment は、ラベルが未使用の場合に料金を返金します。

オプションのスコープ。 次の2つのスコープは認識されますが、デフォルトでは要求されません。

• 3つの注文収益ツール用の https://api.ebay.com/oauth/api_scope/sell.finances.earnings.read。
• すべての Logistics ツール用の https://api.ebay.com/oauth/api_scope/sell.logistics。この API は限定リリースです。

対象のキーセットでは、必要な他のスコープを維持したままスコープを EBAY_OAUTH_SCOPES に追加し、OAuth の同意を再度行ってください。

デジタル署名（EU／UK の出品者）。 eBay では、EU または UK に居住する出品者について、Finances API のすべての呼び出しと issueRefund に デジタル署名が必要です。署名がない場合、eBay は 403 Missing x-ebay-signature-key header を返します。署名を有効にするには、次の手順を実行してください。

1. ebay_create_signing_key を実行します（ED25519 を推奨）。応答は必ず保管してください。eBay は秘密鍵を再表示しません。
2. EBAY_SIGNING_KEY_JWE にその jwe を、EBAY_SIGNING_PRIVATE_KEY にその privateKey を設定し（返された Base64 値、または PEM キー）、サーバーを再起動します。

これらの呼び出しには x-ebay-signature-key、Content-Digest、Signature-Input、Signature の各ヘッダー（RFC 9421）が付加されます。それ以外の呼び出しには署名されず、2つの変数が未設定の場合、動作は変わりません。EBAY_MCP_API_BASE_URL の背後で実行する場合、呼び出しは転送先の eBay のホストとパス（api.ebay.com または apiz.ebay.com）に対して署名されるため、プロキシは eBay の Host ヘッダーと元の eBay パスを転送する必要があります。

eBay MCP と eBay の生 API の比較

どちらも同じ eBay エンドポイントと通信します。違いは、それ以外に自分で構築する必要があるものすべてです。

ワンクリック AI セットアップ

AI アシスタントにセットアップを任せましょう。 下のプロンプトをコピーして、Claude、ChatGPT、または MCP に対応した任意の AI アシスタントに貼り付けてください。

I want to set up the eBay MCP Server for my AI assistant. Please help me:

1. Install the eBay MCP server:
   npm install -g ebay-mcp

2. I need to configure it for [Claude Desktop / Cursor / Cline / Zed / Continue.dev / Windsurf / Claude Code CLI / Amazon Q] (choose one)

3. My eBay credentials are:
   - Client ID: [YOUR_CLIENT_ID]
   - Client Secret: [YOUR_CLIENT_SECRET]
   - Environment: [sandbox / production]
   - Redirect URI (RuName): [YOUR_REDIRECT_URI]

Please:
- Create the appropriate config file for my MCP client
- Set up the environment variables
- Help me complete the OAuth flow to get a refresh token for higher rate limits
- Test that the connection works

If I don't have eBay credentials yet, guide me through creating a developer account at https://developer.ebay.com/

クイックスタート

1. eBay の認証情報を取得する

1. 無料の eBay Developer Account を作成します。
2. Developer Portal でアプリケーションキーを生成します。
3. Client ID と Client Secret を保存します。

2. インストールする

npm install -g ebay-mcp            # from npm (recommended)

または、ソースからインストールします。

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp && npm install && npm run build

3. セットアップウィザードを実行する

npm run setup

ウィザードで eBay の認証情報を設定し、OAuth（より高いレート制限に対応）をセットアップします。また、MCP クライアントを自動検出して設定し、すべてを自動的に保存します。

4. 読み取り専用リクエストで確認する

MCP クライアントを再起動し、次のように尋ねます。

「eBay API のレート制限を確認してください。」

ebay_get_rate_limits または ebay_get_user_rate_limits が呼び出され、販売者データを変更せずに、サーバー、認証情報、MCP クライアントの設定を確認できます。

5. 使用する

AI アシスタントを使って eBay の管理を始めましょう。まずは読み取り専用の質問から始め、対象環境がサンドボックスか本番環境かを確認してから、在庫、注文、キャンペーンを変更するツールを使ってください。

デモ

Claude Desktop で eBay MCP サーバーが動作する様子をご覧ください。

https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b

設定

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox            # or "production"
EBAY_REDIRECT_URI=your_runame
EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
# EBAY_SITE_ID=0                    # Trading API site override; defaults from EBAY_MARKETPLACE_ID
EBAY_CONTENT_LANGUAGE=en-US         # default request content language
EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
# EBAY_SIGNING_KEY_JWE=<jwe>         # Digital Signatures for EU/UK sellers (jwe from ebay_create_signing_key)
# EBAY_SIGNING_PRIVATE_KEY=<key>     # privateKey from the same response (base64 PKCS#8 or PEM)
EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)
EBAY_READ_ONLY=false                # when true, only register read-only tools (gets/lists/searches)
# Local photo/video upload (optional — off until a directory is allowed):
# EBAY_MCP_MEDIA_DIRS=/srv/media    # path-delimited directories the media and feed upload tools may read
# EBAY_MCP_MEDIA_ROOT=/srv/media    # root for media://<relative-path> references (also allowed)
# HTTP deploy (optional — Docker / Railway / self-hosted):
# MCP_HOST=0.0.0.0                  # default is 0.0.0.0 when PORT is set
# MCP_PORT=3000                     # preferred over platform PORT
# MCP_AUTH_TOKEN=secret             # static Bearer for HTTP MCP (skips OAuth verifier)
# MCP_CORS_ORIGINS=https://app.example.com  # browser origins allowed cross-origin (comma-separated); default: loopback origins only

利用可能なツール

AI アシスタントに依頼するような、よくあるタスクの例です。

• OAuth を設定する — 「eBay アカウントの OAuth 設定を手伝ってください。」 → ebay_get_oauth_url を使って認証 URL を生成し、リフレッシュトークンを設定します。これにより、1 日あたり 1 万～5 万件のリクエストが可能になります。
• 在庫を管理する — 「有効な出品をすべて表示してください。」 → ebay_get_inventory_items が SKU、数量、ステータスを返します。
• 出品に写真を追加する — 「~/listings/megadrive にある 3 枚の写真を SKU MD-001 に添付してください。」 → ebay_attach_media_to_inventory_item が写真を eBay Picture Services にアップロードし、product.imageUrls を更新します（EBAY_MCP_MEDIA_DIRS を設定すると、そのフォルダーを使用できます）。
• オークションを実施する — 「この SKU を 7 日間のオークションとして、開始価格 9.99 ドル、最低落札価格 25 ドルで出品してください。」 → format: "AUCTION"、auctionStartPrice、auctionReservePrice、listingDuration: "DAYS_7" を指定して ebay_create_offer を呼び出し、その後 ebay_publish_offer を呼び出します。旧方式では、format: "AUCTION" と Trading の Item（StartPrice、ReservePrice、ListingDuration: "Days_7"）を指定して ebay_create_listing を呼び出します。
• オファーを検索する — ebay_get_offers は、必須の SKU を 1 つ指定すると、その SKU のオファーを返します。在庫全体のオファーを列挙するには、まず ebay_get_inventory_items を呼び出し、その後 SKU ごとに ebay_get_offers を 1 回ずつ呼び出します。
• フルフィルメントポリシーを管理する — 「配送ポリシーを作成してから、処理時間を更新してください。」 → ebay_create_fulfillment_policy が再利用可能なポリシー ID を作成し、ebay_update_fulfillment_policy がその設定を置き換えます。
• 注文を処理する — 「過去 7 日間の未処理注文をすべて取得してください。」 → 日付とフルフィルメントステータスのフィルターを指定して ebay_get_orders を呼び出します。
• キャンペーンを作成する — 「電子機器のプロモーション出品キャンペーンを作成してください。」 → ebay_create_campaign と関連するマーケティングツールを使用します。
• 一括操作を行う — 「『Vintage Watches』の商品すべてに 10% の割引を適用してください。」 → 該当する商品に対して ebay_get_inventory_items と ebay_update_offer を使用します。

対象範囲と安全性

• 非公式プロジェクトです。 これは eBay の製品ではなく、お使いの eBay Developer アカウントで認められている範囲を超える API 権限を付与するものではありません。
• ローカルサーバーからライブ API に接続します。 MCP サーバーはお使いのマシン上で動作しますが、ツールはインターネット経由で eBay のサンドボックス API または本番 API を呼び出します。
• 変更を行うツールはセラーデータを変更する場合があります。 在庫、フルフィルメント、マーケティング、アカウント、フィード、ストア、Trading の各ツールは、eBay のレコードを作成、修正、返金、終了、またはその他の方法で更新する場合があり、ebay_create_shipment_from_shipping_quote は送料を購入します。まずサンドボックスでテストしてください。
• ツールの公開範囲は設定できます。 より小さく、ワークフローに特化したツール群を使う場合は、EBAY_MCP_TOOLS=dynamic またはツールのカテゴリ一覧を指定してください。
• インタラクティブビューは読み取り専用です。 MCP Apps ビューでは、読み取りツールを使ってページ移動、更新、詳細表示ができますが、eBay のデータは変更されません。
• コンプライアンスは利用者の責任です。 認証情報を安全に管理し、レート制限を監視し、eBay の API 利用規約とデータ取り扱いルールに従ってください。

ログとトラブルシューティング

• ログ — Winston ベースで、stderr（MCP セーフ）に出力されます。オプションでファイルにも出力できます。
• トラブルシューティング — サーバーが表示されない、認証エラー、レート制限、結果が空などの問題が発生した場合は、npm run diagnose から始めてください。

よくある質問

貢献

貢献を歓迎します。フォーク → ブランチ作成 → テスト追加 → 以下のチェックを実行 → Conventional Commits に沿ってコミット → PR を作成してください。

pnpm typecheck && pnpm typecheck:mcp-apps   # TypeScript (server + MCP Apps views)
pnpm check:ci                              # Biome lint + format
pnpm test && pnpm test:integration         # Vitest unit + integration
pnpm build                                 # Build to build/

プッシュする前に Docker で CI ゲートをローカル実行するには、act を使用してください：act workflow_dispatch -W .github/workflows/ci.yml。マシンの ~/.actrc で、ランナー、アーキテクチャ、共有キャッシュを選択します。

リソース

プロジェクトのドキュメント：

• llms.txt — AI エージェント向けの簡潔なプロジェクト概要です。
• リリース と Issue トラッカー。

公式仕様とツール：

• eBay Developer Portal、Sell API ドキュメント、API ライセンス契約、データ取り扱い要件、API ステータス。
• Model Context Protocol と MCP Apps SDK。
• Node.js、npm パッケージ、TypeScript、Zod、Effect、Biome、Vitest、GitHub Actions。
• Claude Code と llms.txt。

ライセンス

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

コントリビューター

このプロジェクトの改善にご協力いただいた皆様、ありがとうございます！🎉