ebay-deal-hunter

ebay-mcp

A read-only Model Context Protocol server that wraps the eBay Browse API for keyword search and item detail lookup. Intended for personal homelab deal-hunting via Claude Code and Claude Desktop. Written in Python, runs locally over stdio.

Plugin install (local dev)

The whole repo is a Claude Code plugin. To try it locally:

cd /Users/conrad/Ai/ebay_mcp
uv pip install -e .   # one-time, sets up the MCP server in a venv
claude --plugin-dir .

Inside the Claude Code session, you will be prompted for ebay_client_id and ebay_client_secret on first MCP activation. Get them from eBay's developer portal. The skill, commands /ebay-deal-hunter:hunt and /ebay-deal-hunter:deal-check, and both MCP tools (search_ebay, get_item) become available.

Manual install (MCP only, no plugin)

If you want only the MCP server (no skill, no slash commands), register it with Claude Code at user scope instead:

cd /Users/conrad/Ai/ebay_mcp
uv venv --python 3.12
uv pip install -e .

claude mcp add ebay_mcp \
  --scope user \
  --env EBAY_CLIENT_ID=YOUR_EBAY_CLIENT_ID \
  --env EBAY_CLIENT_SECRET=YOUR_EBAY_CLIENT_SECRET \
  -- uv run --directory /Users/conrad/Ai/ebay_mcp ebay-mcp

See docs/design.md section 7 for Claude Desktop registration and other client wiring.

Repo layout

ebay-mcp/
├── .claude-plugin/plugin.json     # plugin manifest
├── .mcp.json                       # MCP server declaration for the plugin
├── CLAUDE.md                       # repo-specific working notes for Claude Code
├── commands/                       # user-invoked slash commands
│   ├── hunt.md                     # /ebay-deal-hunter:hunt <query>
│   └── deal-check.md               # /ebay-deal-hunter:deal-check <itemId>
├── docs/
│   ├── design.md                   # full design, the authoritative read
│   ├── supply-chain-baseline.md    # pinned-deps audit baseline
│   └── superpowers/                # archived plan + spec for the v1 test suite
├── ebay_mcp.py                     # the MCP server (uses mcp SDK FastMCP)
├── pyproject.toml                  # mcp==1.27.0, httpx==0.28.1 (pinned)
├── scripts/
│   ├── manual-test.sh              # one-shot runner: venv, pytest, supply-chain
│   └── supply-chain-check.sh       # re-runs the §8.2 audit, exits non-zero on drift
├── skills/
│   └── deal-hunter/SKILL.md        # model-invoked deal-hunting heuristics
└── tests/                          # 24 tests: smoke, unit, stdio-protocol, live-API

Running the tests

uv run --with pytest pytest tests/ -v      # 21 pass, 3 skip without creds
bash scripts/manual-test.sh                # orchestrated run with log archival

Set EBAY_CLIENT_ID / EBAY_CLIENT_SECRET (or drop a .env at the repo root) to unlock the 3 live integration tests.

Status

v1 shipped 2026-04-21. Both tools are live, validated end to end against the production Browse API, and registered with Claude Code (user scope) and Claude Desktop. See docs/design.md §12a for the validation log, and CLAUDE.md for working notes and locked decisions.

License

MIT.