内容
# eBay MCP
eBay买家端工作流的MCP服务器：搜索、关注、出价、购买、管理我的eBay。混合栈——现代Buy/Browse REST API用于搜索和商品查询，传统Trading API（2026年仍可使用）用于所有有状态操作。
> ⚠️ **测试版（v0.5.0）。** Browse + Trading API已连接，支持沙盒和生产环境。所有15种工具都已在生产环境中验证通过——包括三种需要资金承诺的工具，它们已用于通过安全栈（确认金额门槛 + 500美元上限 + 操作系统模态确认对话框）完成实际的eBay交易。在启用生产环境之前，请阅读[资金承诺](#资金承诺-高风险-安全门槛)部分。
## 范围
### 只读（低风险）
- `search`，`get_item`（Browse API）
- `get_watchlist`，`get_active_bids`，`get_won_items`，`get_lost_items`，`get_purchase_history`（Trading API）
### 关注列表写入（低风险——无资金承诺）
- `add_to_watchlist`，`remove_from_watchlist`
### 资金承诺（高风险——安全门槛）
- `place_bid(item_id, max_bid_amount, confirm_amount, ...)` —— Trading `PlaceOffer` with `Action=Bid`. 对拍卖品进行代理出价。
- `buy_now(item_id, confirm_amount, ...)` —— Trading `PlaceOffer` with `Action=Purchase`. 提交购买。
- `make_best_offer(item_id, offer_amount, confirm_amount, ...)` —— Trading `PlaceOffer` with `Action=BestOffer`. 提交卖家可以接受/拒绝/取消的报价。
**安全栈（每个资金工具）：**
1. **确认金额门槛。** 每次调用都需要`confirm_amount`与出价/购买/报价金额完全相等。LLM必须重复美元数字；不匹配返回结构化拒绝载荷（不是异常），以便LLM可以读取并重试，修正参数。
2. **每笔调用500美元上限。** 金额超过500美元的调用会因`reason: "cap_exceeded"`而被拒绝。两种方法可以授权更高支出：
- **每笔调用：** 在工具调用时传递`max_bid_override >= amount`。较低的覆盖会因`reason: "override_too_low"`而被拒绝。
- **操作员范围：** 在MCP服务器的环境中设置`EBAY_MCP_ALLOW_HIGH_VALUE=1`。
3. **人工确认对话框。** 在程序门槛清除后，MCP会弹出最顶层的系统模态确认对话框（Windows：通过`ctypes`使用`MessageBoxW`；macOS/Linux：`tkinter.messagebox`），显示工具、主机、商品ID、金额、货币和数量。默认按钮为**否**，ESC取消，没有自动关闭或超时。点击**是**将调用发送到eBay；其他操作返回`reason: "user_declined"`拒绝，不会触发Trading调用。**故意没有环境变量绕过** —— 测试直接存根对话框。生产主机对话框带有`*** 生产主机 — 真实资金 ***`头部；沙盒对话框显示`沙盒主机（无真实资金）`。
4. **活动主机可见性。** 对`default_host = "production"`的成功调用在响应中包含一个`warning`字段（`"生产主机 — 此调用已在eBay上提交真实资金"`）。`server_info()`在任何调用之前标记活动主机。
5. **没有沉默的半承诺。** 没有身份验证令牌缓存 → 底层Trading API调用在触及eBay之前引发，而不是在飞行途中。
所有资金工具还通过`TradingApiError`将eBay侧错误（出价不足、货币不匹配、列表已结束等）显示为已解析的`Errors`块。
### 不在范围内（v0）
- ❌ 销售侧（直接使用eBay的Sell API — 形状完全不同）
- ❌ 自动触发的狙击出价（一次工具调用 = 一次出价，无需调度）
- ❌ 多账户：v0是每个主机配置一个用户账户；如有需要，后期添加多账户
## 安装
> 暂未在PyPI上发布。从源码开始：
```bash
git clone https://github.com/acato/ebay-mcp
cd ebay-mcp
uv sync
uv run ebay-mcp
```
### Windows：避免Microsoft Store Python
如果`uv`在创建虚拟环境时选择了Microsoft Store Python（路径位于`\WindowsApps\PythonSoftwareFoundation...`下），则MCP可以从终端运行，但无法从Claude桌面应用、IDE扩展或计划任务等GUI主机启动。您将看到：
```
Unable to create process using "...\WindowsApps\PythonSoftwareFoundation.Python.3.12_...\python.exe"
```
将`uv`固定到非商店解释器 — uv的托管Python最简单：
```powershell
uv python install 3.12
uv venv --python 3.12 --python-preference only-managed --clear
uv sync
```
验证：`Get-Content .venv\pyvenv.cfg` — `home =`行应指向`AppData\Roaming\uv\python\...`，**而不是** `\WindowsApps\`。
## 配置
先使用沙盒。从[developer.ebay.com](https://developer.ebay.com) → 应用程序密钥集 → 沙盒获取沙盒密钥集。将`examples/config.toml`复制到`~/.config/ebay-mcp/config.toml`:
```toml
default_host = "sandbox"
[hosts.sandbox]
app_id = "..." # SBX 应用 ID（客户端 ID）
dev_id = "..." # 开发人员账户 Dev ID
cert_id = "..." # SBX 证书 ID（客户端密钥）—— 环境变量优先
redirect_uri = "https://localhost/oauth/callback"
# [hosts.production]
# app_id = "..."
# dev_id = "..."
# cert_id = "..."
# redirect_uri = "https://localhost/oauth/callback"
```
主机环境变量覆盖文件值：
- `EBAY_MCP_<HOST>_CERT_ID` — 覆盖`cert_id`（建议用于生产）
- `EBAY_MCP_<HOST>_APP_ID`，`EBAY_MCP_<HOST>_DEV_ID` — 完整性覆盖
用户级OAuth令牌缓存自动存储到`~/.config/ebay-mcp/token-cache-<host>.json`，在手动授权码流程后（参见`auth.py`文档）。
## 与Claude Code一起使用
```bash
claude mcp add ebay-mcp -- uv run --directory /path/to/ebay-mcp ebay-mcp
```
## 与Claude Desktop一起使用
添加到`claude_desktop_config.json`:
```json
{
"mcpServers": {
"ebay-mcp": {
"command": "C:\\Users\\you\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe",
"args": ["run", "--directory", "C:\\path\\to\\ebay-mcp", "ebay-mcp"]
}
}
}
```
## 文档
- [DESIGN.md](DESIGN.md) — 架构、工具表面、安全模式、OAuth流程
- [CONTRIBUTING.md](CONTRIBUTING.md) — 开发设置、沙盒测试、发布流程
## 许可证
Apache 2.0。参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
## 商标
"eBay"是eBay Inc.的商标。本项目是与标准的eBay公共API进行独立集成，不隶属于eBay Inc.，不被eBay Inc.认可或赞助。
