# ebay-mcp

[eBay Developers Program](https://developer.ebay.com/) の **OAuth 2.0（User access token）** で呼び出す REST API を、Cursor / Claude から使うための [Model Context Protocol](https://modelcontextprotocol.io/) サーバーです。

実行には **Python 3.10 以上**が必要です。macOS の `/usr/bin/python3` が 3.9 の場合は、`/opt/homebrew/bin/python3.11 -m venv .venv` のように新しいランタイムで仮想環境を作成してください。

## 対応していること

- **Commerce Identity** — サインインしたアカウントのプロフィール検証（`GET /commerce/identity/v1/user/`）
- **Buy Browse** — `item_summary/search` と単品 `item/{id}` の取得
- **トークン更新** — `EBAY_REFRESH_TOKEN` があれば 401 時に自動でリフレッシュを試行（プロセス内のみ）
- **OAuth 補助** — `ebay-mcp-auth` で Authorization Code を取得し、`mcp.json` 用の `env` 断片を表示

## 環境変数（秘密情報はコードに書かない）

| 変数 | 例 / 説明 |
|------|-----------|
| `EBAY_ENV` | `sandbox`（既定）または `production` |
| `EBAY_CLIENT_ID` | Developer Portal の **App Id（OAuth Client Id）** |
| `EBAY_CLIENT_SECRET` | **Cert Id（Client Secret）**。漏洩したら Dev Console で **Rotate / 再発行** してください |
| `EBAY_ACCESS_TOKEN` | User access token（`ebay-mcp-auth` の出力）。**未設定でも可** — App/Cert のみなら自動で OAuth **application token**（client_credentials）を取得して Browse を叩きます |
| `EBAY_REFRESH_TOKEN` | 推奨（User モード時）。application のみ運用では不要 |
| `EBAY_ALLOW_APPLICATION_TOKEN` | `true`（既定）/ `false`。`false` にすると User トークン必須にできます |
| `EBAY_APPLICATION_SCOPE` | application token 用 scope（既定 `https://api.ebay.com/oauth/api_scope`） |
| `EBAY_MARKETPLACE_ID` | 既定 `EBAY_US`（Browse 系でヘッダに付与） |
| `EBAY_DEVELOPER_ID` | 任意。将来の Notification 等で使う場合に |
| `EBAY_OAUTH_SCOPE` | `ebay-mcp-auth` 用。未指定なら Identity + ベーススコープ |
| `EBAY_REDIRECT_URI` | `ebay-mcp-auth` 用。**Dev Console に登録した Ru Name / Redirect URL と完全一致** |
| `EBAY_OAUTH_LOCAL_PORT` | 既定 `8765`（ローカルコールバック待受） |

ユーザーがチャットなどに貼った **Cert Id は無効化（ローテーション）済みとして扱い**、`mcp.json` の env のみへ再設定することを強く推奨します。

## 初回: ユーザートークンの取得（`ebay-mcp-auth`）

1. Keys → **User Tokens (OAuth)** で **Ru Name** に次と一致する Redirect URL を登録  
   （例）`https://127.0.0.1:8765/callback`
2. 端末から:

```bash
cd projects/ebay-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

export EBAY_ENV=sandbox
export EBAY_CLIENT_ID="<App Id>"
export EBAY_CLIENT_SECRET="<Cert Id>"
export EBAY_REDIRECT_URI="https://127.0.0.1:8765/callback"

python -m ebay_mcp.auth
```

ブラウザで eBay にサインインし、許可後に自動で localhost に戻ります。表示された **`mcp.json` フラグメント** の `env` を Cursor の MCP 設定へマージします。

コードだけ貼った場合は、リダイレクト URL に含まれる `code=` を次のように渡します。

```bash
ebay-mcp-auth --code '<code の値のみ>'
```

Browse 検索などで権限エラーになる場合は、Dev Console で **追加の OAuth scope** に対応した Ru Name / アプリ権限があるか確認し、`EBAY_OAUTH_SCOPE` を拡張してください。

## 疎通

```bash
EBAY_ENV=sandbox EBAY_CLIENT_ID=... EBAY_CLIENT_SECRET=... EBAY_ACCESS_TOKEN=... EBAY_REFRESH_TOKEN=... \\
  ebay-mcp-check
```

成功時末尾に `OK: end-to-end eBay access works.` が表示されます。

## Cursor 登録

`examples/cursor_mcp_config.example.json` を参考にしてください。公開前は `uvx --from /abs/path/to/projects/ebay-mcp` でローカルパス指定もできます。

---

MIT License © 2026 taka392