🚀 eBay API MCP Server
このサーバーは、Model Context Protocol (MCP) を利用して、AIアシスタントがeBayのSell APIに包括的にアクセスできるようにします。在庫管理、注文履行、マーケティングキャンペーン、分析など、230以上のツールを提供します。
API Coverage: 99.1% (~110 of 111 eBay Sell API endpoints)
⚠️ 免責事項
重要: このソフトウェアを使用する前に、この免責事項を注意深くお読みください。
これはオープンソースプロジェクトであり、明示的または黙示的ないかなる保証も伴わずに「現状のまま」提供されます。このソフトウェアを使用することにより、あなたは以下の事項を承認し、同意するものとします。
-
責任の否認: このプロジェクトの作者、貢献者、およびメンテナは、このソフトウェアの使用によって生じる可能性のある損害、損失、または問題に対して、一切の責任を負いません。これには以下が含まれますが、これらに限定されません。
- データの損失または破損
- 経済的損失
- サービスの中断
- eBayアカウントの停止または終了
- eBayのサービス利用規約またはAPI使用ポリシーの違反
- その他の直接的または間接的な損害
-
eBay APIの使用: このプロジェクトは非公式のサードパーティ実装であり、eBay Inc. とは関係がなく、承認もされておらず、後援もされていません。あなたは以下のことについて独自の責任で行う必要があります。
-
自己責任での使用: このソフトウェアは教育および開発目的で提供されています。ユーザーは以下のことを行う必要があります。
- 本番環境で使用する前に、eBayのサンドボックス環境で十分にテストすること
- 自分のために行われるAPI呼び出しを理解すること
- 重要なデータのバックアップを保持すること
- APIの使用状況とアカウントの状態を監視すること
-
セキュリティ: あなたは以下のことに責任があります。
- API資格情報を安全に保管すること
- 環境変数を適切に構成すること
- MCPサーバーの使用に関するセキュリティ上の影響を理解すること
- セキュリティのベストプラクティスに従うこと
-
保証の無いこと: このソフトウェアは、機能性、信頼性、または特定の目的への適合性に関するいかなる保証も伴わずに提供されます。
このソフトウェアを使用することにより、あなたはすべてのリスクを受け入れ、作者、貢献者、およびメンテナをいかなる請求、損害、または責任から免責することに同意するものとします。
公式のeBay APIサポートについては、eBay Developer Program を参照してください。
📚 目次
- ⚠️ 免責事項
- ✨ 主な機能
- 🚀 クイックスタート
- ⚙️ 設定
- 🛠️ 利用可能なツール
- 💻 使用例
- 🧑💻 開発
- 🤝 コントリビューション
- 🔍 トラブルシューティング
- 📖 リソース
- 📄 ライセンス
✨ 主な機能
- 230以上のeBay APIツール - 在庫、注文、マーケティング、分析など、eBay Sell APIを包括的にカバー
- OAuth 2.0サポート - 自動更新機能を備えた完全なユーザートークン管理
- 型安全性 - TypeScript、Zod検証、およびOpenAPI生成型を使用して構築
- MCP統合 - AIアシスタントとの直接統合のためのSTDIOトランスポート
- スマート認証 - ユーザートークン(1日あたり10,000 - 50,000リクエスト)からクライアント資格情報(1日あたり1,000リクエスト)への自動フォールバック
- 十分にテスト済み - 99%以上の関数カバレッジで870以上のテスト
🚀 クイックスタート
1. eBayの資格情報を取得する
- eBay Developer Account を無料で作成します。
- Developer Portal でアプリケーションキーを生成します。
- Client ID と Client Secret を保存します。
2. インストールする
オプションA: npmからインストールする(推奨)
npm install -g ebay-mcp
オプションB: ソースからインストールする
git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
npm run build
3. 設定する
対話型セットアップウィザードを実行します。
npm run setup
または、手動で設定します。
cp .env.example .env
npm run auto-setup
4. MCPクライアントを設定する
このサーバーをあなたのMCPクライアント設定に追加します。
Claude Desktop:
Claude Desktopの設定ファイルを編集します。
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
サーバー設定を追加します。
{
"mcpServers": {
"ebay": {
"command": "npx",
"args": ["-y", "ebay-mcp"],
"env": {
"EBAY_CLIENT_ID": "your_client_id",
"EBAY_CLIENT_SECRET": "your_client_secret",
"EBAY_ENVIRONMENT": "sandbox",
"EBAY_REDIRECT_URI": "your_runame"
}
}
}
}
代替案: ローカルにインストールされたバージョンを使用する
ソースからインストールした場合:
{
"mcpServers": {
"ebay": {
"command": "node",
"args": ["/absolute/path/to/ebay-mcp/build/index.js"],
"env": {
"EBAY_CLIENT_ID": "your_client_id",
"EBAY_CLIENT_SECRET": "your_client_secret",
"EBAY_ENVIRONMENT": "sandbox"
}
}
}
}
5. 使用する
MCPクライアント(Claude Desktopなど)を再起動し、AIアシスタントを通じてeBayツールを使用し始めます。
⚙️ 設定
📖 すべての環境変数、OAuthフローの手順、およびトラブルシューティングの詳細な説明を含む包括的な設定ガイドについては、設定ドキュメント を参照してください。
環境変数
eBayの資格情報を含む .env ファイルを作成します。
EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox
EBAY_REDIRECT_URI=your_runame
EBAY_USER_REFRESH_TOKEN=your_refresh_token
OAuth認証
クライアント資格情報(自動):
- デフォルトの認証方法
- 1日あたり1,000リクエスト
- クライアントIDとシークレット以外の設定は不要
ユーザートークン(本番環境で推奨):
- 1日あたり10,000 - 50,000リクエスト(アカウントタイプによって異なる)
ebay_get_oauth_url ツールを使用して承認URLを生成する
- OAuthフローの後、
.env に EBAY_USER_REFRESH_TOKEN を追加する
- トークンは自動的に更新される
詳細なOAuth設定と包括的な設定ガイドについては、設定ドキュメント を参照してください。
MCPクライアントの互換性
このサーバーは、STDIOトランスポートをサポートするすべてのMCPクライアントと互換性があります。
テスト済みでサポートされているもの:
- ✅ Claude Desktop (macOS、Windows、Linux) - 完全サポート
- ✅ MCP Inspector - 開発とテスト用
- ✅ カスタムMCPクライアント - STDIOまたはHTTPトランスポートを介して
設定要件:
- MCPプロトコルバージョン: 1.0以上
- トランスポート: STDIO(デフォルト)またはHTTP
- Node.jsランタイム: 18.0.0以上
その他のMCPクライアント:
具体的にテストされていませんが、このサーバーは以下を含むすべてのMCP準拠クライアントで動作するはずです。
- Continue.dev
- MCPサポートを備えた他のエディター
- カスタム実装
このサーバーを他のMCPクライアントで正常に使用した場合は、ディスカッションを開く ことでお知らせください!
レート制限
eBay APIのレート制限を理解することは、本番環境での使用において重要です。
クライアント資格情報(デフォルト):
- 日次制限: 1日あたり1,000リクエスト
- 最適な用途: 開発、テスト、低ボリュームの操作
- 設定: クライアントIDとシークレットだけで自動的に設定されます。
ユーザートークン(推奨):
- 日次制限: 1日あたり10,000 - 50,000リクエスト(アカウントタイプによって異なる)
- 最適な用途: 本番環境、高ボリュームの操作
- 設定: OAuthフローが必要です(
ebay_get_oauth_url ツールを使用)
アカウントタイプ別のレート制限階層:
- 個人開発者: 1日あたり10,000リクエスト
- 商用開発者: 1日あたり25,000リクエスト
- エンタープライズ: 1日あたり50,000以上のリクエスト(カスタム制限)
レート制限のベストプラクティス:
- 本番環境のワークロードにはユーザートークンを使用する
- レート制限エラー時に指数バックオフを実装する
- 可能な場合はレスポンスをキャッシュする
- eBay Developer Portalで使用状況を監視する
- APIがサポートする場合は操作をバッチ処理する
- より高い制限のために開発者アカウントの階層をアップグレードすることを検討する
レート制限の処理:
レート制限に達すると、APIは429ステータスコードを返します。サーバーは以下のことを行います。
- 指数バックオフで自動的に再試行する
- レート制限エラーを通知する
- ユーザートークン認証へのアップグレードを提案する
現在の使用状況を確認する:
ebay Developer Portal でAPIの使用状況を監視します。
🛠️ 利用可能なツール
サーバーは、以下のカテゴリに分類された230以上のツールを提供します。
- アカウント管理 - ポリシー、プログラム、サブスクリプション、消費税
- 在庫管理 - 商品、オファー、場所、一括操作
- 注文履行 - 注文、配送、返金、紛争
- マーケティングとプロモーション - キャンペーン、広告、プロモーション、入札
- 分析 - トラフィックレポート、セラー基準、メトリクス
- コミュニケーション - 買い手と売り手のメッセージング、交渉
- メタデータと分類体系 - カテゴリ、商品の側面、ポリシー
- トークン管理 - OAuth URL生成、トークン管理
ツールの例:
ebay_get_inventory_items - すべての在庫商品をリストする
ebay_get_orders - セラーの注文を取得する
ebay_create_offer - 新しいリスティングオファーを作成する
ebay_get_campaigns - マーケティングキャンペーンを取得する
ebay_get_oauth_url - OAuth承認URLを生成する
完全なツールリストについては、src/tools/definitions/ を参照してください。
💻 使用例
ここでは、eBay MCPサーバーを使用して達成できる一般的なタスクのいくつかを紹介します。
より高いレート制限のためのOAuthの設定
ユーザー: "eBayアカウントのOAuth認証を設定してくれますか?"
アシスタント: ebay_get_oauth_url ツールを使用して承認URLを生成します。あなたはそのURLを訪問し、パーミッションを付与し、アシスタントが .env ファイルにリフレッシュトークンを設定するのを支援します。
結果: 1日あたり1,000リクエストではなく、10,000 - 50,000のAPIリクエストにアクセスできるようになります。
在庫管理
ユーザー: "eBayでのすべてのアクティブなリスティングを表示してください"
アシスタント: ebay_get_inventory_items を使用してすべての在庫商品を取得します。
結果: SKU、数量、およびステータスを含む、あなたのすべての商品のフォーマットされたリストが表示されます。
注文処理
ユーザー: "過去7日間のすべての未履行の注文を取得してください"
アシスタント: 日付フィルターと履行ステータスパラメーターを使用して ebay_get_orders を使用します。
結果: 出荷処理のために準備ができている保留中の注文のリストが返されます。
マーケティングキャンペーンの作成
ユーザー: "電子機器カテゴリのためにプロモートリスティングキャンペーンを作成してください"
アシスタント: ebay_create_campaign および関連するマーケティングツールを使用して広告キャンペーンを設定します。
結果: 指定された予算とターゲット商品で新しいキャンペーンが作成されます。
一括操作
ユーザー: "カテゴリ 'ヴィンテージウォッチ' のすべての商品の価格を10%割引で更新してください"
アシスタント: ebay_get_inventory_items を組み合わせてカテゴリでフィルタリングし、ebay_update_offer を使用して一括価格変更を適用します。
結果: 一致するすべての商品が新しい価格で更新されます。
🧑💻 開発
前提条件
- Node.js >= 18.0.0
- npmまたはpnpm
- eBay Developer Account
セットアップ
git clone https://github.com/YOUR_USERNAME/ebay-mcp.git
cd ebay-mcp
npm install
cp .env.example .env
npm run build
npm test
開発コマンド
npm run dev
npm run dev:http
npm run test
npm run test:watch
npm run typecheck
npm run lint
npm run format
Dockerサポート
コンテナ化された環境でサーバーを実行します。
npm run docker:build
npm run docker:up
npm run docker:logs
npm run docker:down
npm run docker:restart
Docker Composeの設定:
サーバーは、簡単なデプロイのためにDocker Composeで実行できます。
docker-compose up -d
Dockerコマンドを実行する前に、環境変数を .env ファイルに設定する必要があります。コンテナは自動的にあなたの .env 設定を使用します。
Dockerの使用例:
- 本番環境のデプロイ
- 一貫した開発環境
- CI/CDパイプライン
- 分離されたテスト環境
HTTPサーバーモード
MCPクライアントのデフォルトのSTDIOトランスポートに加えて、サーバーはテストとデバッグのためにHTTPモードで実行できます。
npm run dev:http
npm run start:http
HTTPモードの機能:
- すべてのツールのRESTful APIエンドポイント
- 対話型APIドキュメント
- MCPクライアントなしでツールをテストするのに便利
- ウェブアプリケーションのためのCORSサポート
- Helmetセキュリティヘッダー
HTTPモードを使用するタイミング:
- 開発中に個々のツールをテストする場合
- カスタム統合を構築する場合
- APIレスポンスをデバッグする場合
- ウェブベースのインターフェイスを作成する場合
注意: STDIOモード(デフォルト)は、MCPクライアント(Claude Desktopなど)との統合に推奨されます。HTTPモードは主に開発とカスタム統合のために使用されます。
プロジェクト構造
ebay-mcp/
├── src/
│ ├── index.ts # MCPサーバーのエントリポイント
│ ├── api/ # eBay APIの実装
│ ├── auth/ # OAuthとトークン管理
│ ├── tools/ # MCPツールの定義
│ ├── types/ # TypeScriptの型
│ └── utils/ # 検証スキーマ
├── tests/ # テストスイート
├── docs/ # ドキュメント
└── build/ # コンパイルされた出力
詳細なコントリビューションガイドラインについては、CONTRIBUTING.md を参照してください。
🤝 コントリビューション
コントリビューションは大歓迎です!以下の手順で始めましょう。
- リポジトリをフォークします。
- 機能ブランチを作成します:
git checkout -b feature/my-feature
- 変更を加え、テストを追加します。
- 品質チェックを実行します:
npm run check && npm test
- Conventional Commits を使用してコミットします。
- あなたのフォークにプッシュし、プルリクエストを開きます。
提出する前に:
- すべてのテストが合格することを確認します。
- TypeScriptのベストプラクティスに従います。
- 必要に応じてドキュメントを更新します。
- テストカバレッジを維持します。
詳細なガイドラインについては、CONTRIBUTING.md を参照してください。
🔍 トラブルシューティング
よくある問題
Claude Desktopにサーバーが表示されない
問題: eBay MCPサーバーがあなたのMCPクライアントに表示されません。
解決策:
- OSに適した設定ファイルのパスが正しいことを確認します。
- JSON構文が有効であることを確認します(JSONバリデーターを使用)。
- 環境変数が適切に設定されていることを確認します。
- Claude Desktopを完全に再起動します。
- Claude Desktopのログにエラーメッセージがないか確認します。
認証エラー
問題: "Invalid credentials" または "Authentication failed" エラーが発生します。
解決策:
EBAY_CLIENT_ID と EBAY_CLIENT_SECRET が正しいことを確認します。
- 正しい環境(サンドボックスまたは本番環境)を使用していることを確認します。
- eBay Developer Portalであなたのアプリケーションキーがアクティブであることを確認します。
- ユーザートークンの場合、
EBAY_USER_REFRESH_TOKEN が有効であることを確認します。
npm run diagnose を実行して設定を確認します。
レート制限エラー
問題: "Rate limit exceeded" エラーが発生します。
解決策:
- ユーザートークン認証にアップグレードします(1日あたり10,000 - 50,000リクエスト)。
- 使用中にリクエストの制限を実装します。
- Developer Portalで現在のレート制限を確認します。
- eBay Developerアカウントの階層をアップグレードすることを検討します。
ツールが正しく動作しない
問題: ツールが予期しないエラーを返すか、空の結果を返します。
解決策:
- 正しい環境(サンドボックスまたは本番環境)を使用していることを確認します。
- 操作に適切なパーミッション/スコープを持っていることを確認します。
- eBay APIのステータスを確認します: https://developer.ebay.com/support/api-status
npm run diagnose:export を実行して診断レポートを生成します。
- eBay APIドキュメント を参照してエンドポイントの要件を確認します。
診断ツール
設定問題をトラブルシューティングするために診断を実行します。
npm run diagnose
npm run diagnose:export
診断ツールは以下を確認します。
- 環境変数の設定
- eBay APIの接続性
- 認証ステータス
- トークンの有効性
- 利用可能なスコープとパーミッション
ヘルプを得る
まだ問題が解決しない場合は、以下のことを行ってください。
- 既存のGitHub Issues を確認します。
- GitHub Discussions を確認します。
- 新しい問題を作成します。
- 診断レポート (
npm run diagnose:export)
- 問題を再現する手順
- エラーメッセージまたはログ
- あなたの環境(OS、Nodeバージョン、MCPクライアント)
📖 リソース
ドキュメント
サポート
📄 ライセンス
このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSE ファイルを参照してください。
🙏 謝辞