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.
