Ebay MCP

🚀 eBay API MCP Server

這是一個基於 Model Context Protocol (MCP) 的服務器，為AI助手提供全面訪問eBay銷售API的能力。它包含230多個工具，可用於庫存管理、訂單履行、營銷活動、分析等多個方面。API覆蓋率達99.1%（約111個eBay銷售API端點中的110個）。

🚀 快速開始

1. 獲取eBay憑證

1. 創建一個免費的 eBay開發者賬戶。
2. 在 開發者門戶 中生成應用程序密鑰。
3. 保存你的 客戶端ID 和 客戶端密鑰。

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
# 使用你的憑證編輯.env文件
npm run auto-setup

4. 配置MCP客戶端

將此服務器添加到你的MCP客戶端配置中：

Claude桌面版： 編輯你的Claude桌面版配置文件：

• 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桌面版等），並通過AI助手開始使用eBay工具。

✨ 主要特性

• 230多個eBay API工具 - 全面覆蓋eBay銷售API，涵蓋庫存、訂單、營銷、分析等多個領域。
• OAuth 2.0支持 - 完整的用戶令牌管理，支持自動刷新。
• 類型安全 - 使用TypeScript構建，結合Zod驗證和OpenAPI生成的類型。
• MCP集成 - 支持STDIO傳輸，可直接與AI助手集成。
• 智能認證 - 當用戶令牌（每天10,000 - 50,000次請求）不可用時，自動切換到客戶端憑證（每天1,000次請求）。
• 測試完善 - 擁有870多個測試用例，函數覆蓋率達99%以上。

📦 安裝指南

安裝方式

選項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

💻 使用示例

基礎用法

以下是一些使用eBay MCP服務器可以完成的常見任務：

設置OAuth以提高速率限制

用戶：“你能幫我為我的eBay賬戶設置OAuth認證嗎？” 助手：使用 ebay_get_oauth_url 工具生成授權URL。你訪問該URL並授予權限後，助手會幫助你在 .env 文件中配置刷新令牌。 結果：每天可訪問10,000 - 50,000次API請求，而不是1,000次。

管理庫存

用戶：“顯示我在eBay上的所有活躍列表” 助手：使用 ebay_get_inventory_items 工具檢索所有庫存項目。 結果：顯示所有產品的格式化列表，包括SKU、數量和狀態。

處理訂單

用戶：“獲取過去7天內所有未完成的訂單” 助手：使用 ebay_get_orders 工具，並設置日期過濾器和履行狀態參數。 結果：返回一個待處理訂單列表，可進行發貨處理。

創建營銷活動

用戶：“為我的電子產品類別創建一個推廣列表活動” 助手：使用 ebay_create_campaign 工具和相關營銷工具設置廣告活動。 結果：根據指定的預算和目標項目創建新的活動。

批量操作

用戶：“將'復古手錶'類別中所有商品的價格降低10%” 助手：結合使用 ebay_get_inventory_items 工具過濾類別，並使用 ebay_update_offer 工具批量更新價格。 結果：所有匹配的商品都更新為新價格。

📚 詳細文檔

配置

📖 如需全面的配置指南，包括所有環境變量的詳細說明、OAuth流程步驟和故障排除，請參閱 配置文檔。

環境變量

創建一個 .env 文件，並使用你的eBay憑證進行配置：

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox  # 或 "production"
EBAY_REDIRECT_URI=your_runame

# 可選：用於更高的速率限制（每天10,000 - 50,000次請求）
EBAY_USER_REFRESH_TOKEN=your_refresh_token

OAuth認證

客戶端憑證（自動）：

• 默認認證方法
• 每天1,000次請求
• 除了客戶端ID和密鑰外，無需其他設置

用戶令牌（生產環境推薦）：

• 每天10,000 - 50,000次請求（根據賬戶類型而定）
• 使用 ebay_get_oauth_url 工具生成授權URL
• 在OAuth流程完成後，將 EBAY_USER_REFRESH_TOKEN 添加到 .env 文件中
• 令牌會自動刷新

如需詳細的OAuth設置和全面的配置指南，請參閱 配置文檔。

MCP客戶端兼容性

此服務器與任何支持STDIO傳輸的MCP客戶端兼容：

已測試並支持的客戶端：

• ✅ Claude桌面版（macOS、Windows、Linux） - 完全支持
• ✅ MCP檢查器 - 用於開發和測試
• ✅ 自定義MCP客戶端 - 通過STDIO或HTTP傳輸

配置要求：

• MCP協議版本：1.0+
• 傳輸方式：STDIO（默認）或HTTP
• Node.js運行時：18.0.0或更高版本

其他MCP客戶端： 雖然未進行具體測試，但該服務器應該與任何符合MCP標準的客戶端兼容，包括：

• Continue.dev
• 其他支持MCP的編輯器
• 自定義實現

如果你成功地將此服務器與其他MCP客戶端一起使用，請通過 開啟討論 告知我們！

速率限制

瞭解eBay API的速率限制對於生產環境的使用至關重要：

客戶端憑證（默認）：

• 每日限制：每天1,000次請求
• 適用場景：開發、測試、低流量操作
• 設置方式：只需提供客戶端ID和密鑰，自動配置

用戶令牌（推薦）：

• 每日限制：每天10,000 - 50,000次請求（根據賬戶類型而定）
• 適用場景：生產環境、高流量操作
• 設置方式：需要進行OAuth流程（使用 ebay_get_oauth_url 工具）

不同賬戶類型的速率限制層級：

• 個人開發者：每天10,000次請求
• 商業開發者：每天25,000次請求
• 企業用戶：每天50,000次以上請求（自定義限制）

速率限制最佳實踐：

1. 在生產環境中使用用戶令牌
2. 在遇到速率限制錯誤時實現指數退避策略
3. 儘可能緩存響應
4. 在eBay開發者門戶中監控你的使用情況
5. 當API支持時，批量執行操作
6. 考慮升級你的開發者賬戶層級以獲得更高的限制

處理速率限制： 當你達到速率限制時，API會返回429狀態碼。服務器將：

• 自動使用指數退避策略重試請求
• 通知你速率限制錯誤
• 建議你升級到用戶令牌認證

檢查當前使用情況： 在 eBay開發者門戶 中監控你的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/。

開發

先決條件

• Node.js >= 18.0.0
• npm或pnpm
• eBay開發者賬戶

設置

# 分叉並克隆倉庫
git clone https://github.com/YOUR_USERNAME/ebay-mcp.git
cd ebay-mcp

# 安裝依賴
npm install

# 設置環境
cp .env.example .env
# 使用你的憑證編輯.env文件

# 構建並測試
npm run build
npm test

開發命令

npm run dev              # 運行STDIO服務器
npm run dev:http         # 運行HTTP服務器
npm run test             # 運行測試
npm run test:watch       # 在監視模式下運行測試
npm run typecheck        # 類型檢查代碼
npm run lint             # 代碼檢查
npm run format           # 格式化代碼

Docker支持

在容器化環境中運行服務器：

# 構建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，適用於Web應用程序
• 包含Helmet安全頭

何時使用HTTP模式：

• 在開發過程中測試單個工具
• 構建自定義集成
• 調試API響應
• 創建基於Web的界面

注意：STDIO模式（默認）推薦用於MCP客戶端集成（如Claude桌面版等）。HTTP模式主要用於開發和自定義集成。

項目結構

ebay-mcp/
├── src/
│   ├── index.ts           # MCP服務器入口點
│   ├── api/               # eBay API實現
│   ├── auth/              # OAuth和令牌管理
│   ├── tools/             # MCP工具定義
│   ├── types/             # TypeScript類型
│   └── utils/             # 驗證模式
├── tests/                 # 測試套件
├── docs/                  # 文檔
└── build/                 # 編譯輸出

如需詳細的貢獻指南，請參閱 CONTRIBUTING.md。

貢獻

歡迎貢獻代碼！以下是開始的步驟：

1. 分叉倉庫
2. 創建一個功能分支：git checkout -b feature/my-feature
3. 進行更改並添加測試
4. 運行質量檢查：npm run check && npm test
5. 使用 Conventional Commits 進行提交
6. 推送到你的分叉倉庫並打開拉取請求

提交前注意事項：

• 確保所有測試通過
• 遵循TypeScript最佳實踐
• 根據需要更新文檔
• 保持測試覆蓋率

如需詳細的貢獻指南，請參閱 CONTRIBUTING.md。

故障排除

常見問題

服務器未出現在Claude桌面版中

問題：eBay MCP服務器未在你的MCP客戶端中顯示。 解決方案：

1. 驗證配置文件路徑是否適用於你的操作系統
2. 檢查JSON語法是否有效（使用JSON驗證器）
3. 確保環境變量已正確設置
4. 完全重啟Claude桌面版
5. 檢查Claude桌面版日誌以獲取錯誤消息

認證錯誤

問題：出現“無效憑證”或“認證失敗”錯誤。 解決方案：

1. 驗證你的 EBAY_CLIENT_ID 和 EBAY_CLIENT_SECRET 是否正確
2. 確保你使用的是正確的環境（沙盒環境還是生產環境）
3. 檢查你的應用程序密鑰在eBay開發者門戶中是否處於活動狀態
4. 對於用戶令牌，驗證你的 EBAY_USER_REFRESH_TOKEN 是否有效
5. 運行 npm run diagnose 檢查你的配置

速率限制錯誤

問題：出現“速率限制已超出”錯誤。 解決方案：

1. 升級到用戶令牌認證（每天10,000 - 50,000次請求）
2. 在使用過程中實現請求限流
3. 在開發者門戶中檢查你當前的速率限制
4. 考慮升級你的eBay開發者賬戶層級

工具無法正常工作

問題：工具返回意外錯誤或空結果。 解決方案：

1. 驗證你使用的是正確的環境（沙盒環境還是生產環境）
2. 確保你對該操作具有適當的權限和範圍
3. 檢查eBay API狀態：https://developer.ebay.com/support/api-status
4. 運行 npm run diagnose:export 生成診斷報告
5. 查看 eBay API文檔 瞭解端點要求

診斷工具

運行診斷程序以排查配置問題：

# 交互式診斷
npm run diagnose

# 導出診斷報告
npm run diagnose:export

診斷工具將檢查：

• 環境變量配置
• eBay API連接性
• 認證狀態
• 令牌有效性
• 可用的範圍和權限

獲取幫助

如果你仍然遇到問題：

1. 檢查現有的 GitHub問題
2. 查看 GitHub討論
3. 創建一個新問題，並提供以下信息：
   • 你的診斷報告（npm run diagnose:export）
   • 重現問題的步驟
   • 錯誤消息或日誌
   • 你的環境（操作系統、Node版本、MCP客戶端）

資源

文檔

• eBay開發者門戶 - API文檔和憑證
• eBay API許可協議 - 使用條款和合規要求
• eBay數據處理要求 - 重要的數據保護和隱私指南
• eBay API狀態 - 即時API健康和狀態
• MCP文檔 - 模型上下文協議規範
• OAuth快速參考 - 完整的OAuth認證指南，包括範圍、故障排除和示例
• OAuth設置指南 - 詳細的認證配置
• 貢獻指南 - 如何為該項目貢獻代碼
• 行為準則 - 社區指南和期望
• 更新日誌 - 版本歷史和發佈說明
• 安全策略 - 漏洞報告指南

支持

• GitHub討論 - 社區問答和一般討論
• 問題跟蹤器 - 錯誤報告和功能請求
• 錯誤報告模板 - 詳細的錯誤報告指南

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

致謝

• eBay開發者計劃 提供API訪問權限
• 模型上下文協議 提供MCP規範
• 所有 貢獻者 幫助改進了這個項目

---

⚠️ 重要提示

在使用本軟件之前，請仔細閱讀以下免責聲明。本項目是一個 開源項目，按“原樣”提供，不提供任何形式的明示或暗示保證。使用本軟件即表示您承認並同意以下內容：

• 無責任聲明：本項目的作者、貢獻者和維護者對使用本軟件可能產生的任何損害、損失或問題 不承擔任何責任，包括但不限於：數據丟失或損壞、財務損失、服務中斷、eBay賬戶暫停或終止、違反eBay的服務條款或API使用政策，以及任何其他直接或間接損害。
• eBay API使用：本項目是一個非官方的第三方實現，與eBay公司沒有關聯、未得到其認可或贊助。您獨自負責：遵守 eBay的API使用條款、確保您的使用在eBay的速率限制和政策範圍內、安全管理您的eBay開發者憑證、理解並遵守 eBay的數據處理要求，以及通過API執行的任何操作。
• 自擔風險使用：本軟件僅用於教育和開發目的。用戶必須：在生產使用之前在eBay的沙盒環境中進行全面測試、理解代表其進行的API調用、備份關鍵數據、監控其API使用和賬戶狀態。
• 安全責任：您負責：確保您的API憑證安全、正確配置環境變量、理解MCP服務器使用的安全影響，以及遵循安全最佳實踐。
• 無保證聲明：本軟件不保證其功能、可靠性或適用於特定目的。

使用本軟件即表示您承擔所有風險，並同意免除作者、貢獻者和維護者的任何索賠、損害或責任。如需官方eBay API支持，請參考 eBay開發者計劃。