eBay Browse

ebay-mcp

インターネット最大の中古マーケットプレイスから、AI エージェントに実際の最新市場価格を直接提供します。

eBayは、実物が今いくらで取引されているかを常に更新する台帳です。eBayのB rowse APIをMCP サーバーとしてラップし、3つのツールを提供します。エージェントは出品を検索したり、個別の商品を取得したり、そして最も便利な機能として、あらゆる商品の価格の全体像（最小値、中央値、最大値、状態別内訳）を取得したりできます。

Python 3.12+ · MIT · MCP サーバー · アプリトークン認証、ユーザーログイン不要

必要なのは、無料のeBayアプリキーセットを1つ設定するだけです。ユーザーログインも、クリックして進むOAuth同意画面もありません。エージェントを接続して「RTX 5080は実際いくらで買える？」と尋ねると、状態別の内訳と最安値の出品情報を添えた、根拠のある回答が1回の呼び出しで返ってきます。

---

目次

• 3つのツール
• アーキテクチャ：1つのクライアント、3つのツール
• 認証：キャッシュ付きクライアント認証情報
• ebay_price_check：価格の全体像の構築方法
• インストール
• 設定
• サンドボックスと本番環境
• プロジェクト構成
• ライセンス

---

3つのツール

ツール	機能
ebay_price_check	検索語に対する価格の全体像を集計して返します。件数、最小値／中央値／最大値、状態別内訳、最安値の出品情報を含みます。中心となるツールです。
ebay_search	並べ替えとフィルタリングに対応した出品検索です。{itemId, title, price, condition, seller, itemWebUrl}の形式で整えた行を返します。
ebay_get_item	IDを指定して、1つの商品について詳細情報を取得します。

// ebay_price_check  ·  query: "RTX 5080", exclude: ["laptop", "notebook"]
{
  "count": 47, "currency": "USD",
  "min": 899, "median": 1099, "max": 2200,
  "by_condition": {
    "New":  { "count": 18, "min": 1099, "median": 1199, "max": 1634 },
    "Used": { "count": 21, "min": 899,  "median": 1050, "max": 1499 }
  },
  "cheapest": [ { "price": 899, "condition": "Used", "title": "…", "itemWebUrl": "…" } ]
}

---

アーキテクチャ：1つのクライアント、3つのツール

すべてのツールは、トークンを管理してeBayと通信する単一のEbayBrowseClientを経由します。認証情報を読み込む場所も、トークンをキャッシュする場所も、HTTP通信を行う場所もそれぞれ1か所に集約されているため、処理にばらつきが生じません。

flowchart LR
    Agent(["AI agent / Claude"])
    subgraph server["ebay-mcp · stdio server"]
        Tools["ebay_search<br/>ebay_get_item<br/>ebay_price_check"]
        Client["EbayBrowseClient"]
        Cache[("OAuth token<br/>in-memory, auto-refresh")]
    end
    Cfg["~/.ebay-mcp.toml<br/>or env vars"]
    eBay["eBay Browse API"]

    Agent -->|"MCP tool call"| Tools
    Tools -->|"search / get_item"| Client
    Client <-->|"reuse or mint token"| Cache
    Client -->|"Bearer token + query"| eBay
    eBay -->|"listings JSON"| Client
    Cfg -.->|"keyset + active env"| Client

サーバーは非同期で動作します。クライアントは通常の同期型requestsを使用し、スレッド（asyncio.to_thread）で実行するため、eBayへの呼び出しが遅くてもイベントループはブロックされません。ebay_price_checkは、単に結果を受け渡すだけでなく、検索後に結果を集計する唯一のツールです（以下を参照）。

---

認証：キャッシュ付きクライアント認証情報

eBayのBrowse APIではアプリケーショントークン（OAuthクライアント認証情報グラント）を使用するため、ユーザーは関与しません。クライアントは初回使用時にトークンを取得してメモリにキャッシュし、有効期限が近づくと自動的に更新します。利用者が意識する必要はありません。

sequenceDiagram
    participant T as Tool call
    participant C as EbayBrowseClient
    participant O as eBay OAuth
    participant B as Browse API

    T->>C: search("RTX 5080")
    alt token missing or expired
        C->>O: POST /identity/v1/oauth2/token<br/>Basic(app_id:cert_id), grant=client_credentials
        O-->>C: access_token + expires_in
        Note over C: cache until (expires_in − 60s)
    end
    C->>B: GET /item_summary/search<br/>Authorization: Bearer …
    B-->>C: listings JSON
    C-->>T: parsed results

60秒のバッファを設けているため、トークンは少し早めに期限切れとして扱われます。これにより、呼び出しの途中でトークンが失効することを防ぎます。トークンの有効期間は約2時間なので、通常は1回の取得で長時間のセッションをカバーできます。

---

ebay_price_check：相場の算出方法

ほかの2つのツールは薄いラッパーです。このツールこそがプロジェクトの存在意義です。生の出品情報の山を、相場の判断に使える数値へと変換します。

flowchart LR
    Q["query<br/>+ exclude[]"] --> S["search<br/>(up to 50 listings)"]
    S --> F["drop excluded titles<br/>+ unpriced listings"]
    F --> G["group by condition"]
    G --> A["aggregate<br/>min · median · max"]
    G --> H["cheapest N<br/>(the tail)"]
    A --> R(["{ count, min, median, max,<br/>by_condition, cheapest }"])
    H --> R

exclude を使うと、数値を正確にできます。「RTX 5080」で検索すると、ノートパソコンや組み立て済みPCが大量に含まれますが、exclude: ["laptop", "notebook", "prebuilt"] を指定すれば除外でき、中央値に実際のグラフィックカードの価格が反映されます。by_condition による分類も同じくらい重要です。新品未開封と使い古された中古品を混ぜた「中央値」はノイズにすぎません。コンディション別に分ければ、それぞれの価格帯の実態がわかります。

知っておくべき重要な制限が1つあります。Browse API が返すのは出品中の希望価格であり、売買成立価格ではありません。最安値は「現在掲載されている最安価格」であり、「実際に売れた価格」ではないと考えてください。

---

インストール

git clone https://github.com/cunicopia-dev/ebay-mcp
cd ebay-mcp
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .

（無料の）eBay 開発者用アプリケーションキーセットが必要です。5分でできる手順はdocs/SETUP.mdをご覧ください。その後、MCP クライアントに設定します。

{
  "mcpServers": {
    "ebay": { "command": "/path/to/ebay-mcp/.venv/bin/ebay-mcp" }
  }
}

---

設定

認証情報は環境変数（優先度が最も高い）または**~/.ebay-mcp.toml**ファイルから取得されます。有効な env を切り替えると、キーセットと API のベース URL が一緒に選択されるため、本番環境の認証情報が誤ってサンドボックスを参照したり、その逆が起きたりすることはありません。

flowchart TD
    Start(["load_config()"]) --> Env{"EBAY_ENV /<br/>EBAY_*_APP_ID<br/>in environment?"}
    Env -->|"set"| UseEnv["take keyset<br/>from env vars"]
    Env -->|"unset"| Toml{"~/.ebay-mcp.toml<br/>present?"}
    Toml -->|"yes"| UseToml["take keyset<br/>from TOML"]
    Toml -->|"no"| Default["default env = production<br/>(error if creds missing)"]
    UseEnv --> Pick["env → keyset + base URL<br/>(locked together)"]
    UseToml --> Pick
    Default --> Pick

# ~/.ebay-mcp.toml   (chmod 600)
env = "production"

[production]
app_id  = "YourApp-PRD-..."
cert_id = "PRD-..."

[sandbox]
app_id  = "YourApp-SBX-..."
cert_id = "SBX-..."

いつでも現在有効な設定を確認できます。出力では認証情報がマスクされます。

ebay-mcp-config
# env:      production
# app_id:   Keit****87dd
# cert_id:  PRD-****0914
# api_base: https://api.ebay.com
# OK — configuration is valid.

---

サンドボックスと本番環境

env を sandbox と production の間で切り替えると、環境を変更できます。コードは同じで、エンドポイントとキーセットが異なります。サンドボックスは認証フローの接続確認に適していますが、在庫は少なく、あらかじめ用意されたものだけです。そのため、実際の価格を調べるには本番環境用のキーセットが必要です。

---

プロジェクトの構成

src/ebay_mcp/
  config.py    # env + TOML loader; ebay-mcp-config CLI
  browse.py    # EbayBrowseClient — OAuth cache + search / get_item
  server.py    # MCP server: list_tools / call_tool / main
tests/         # config precedence, aggregation, tool listing (no network)
docs/SETUP.md  # getting an eBay keyset

---

ライセンス

MIT