shopping-mcp

Un servidor MCP que permite a Claude (o a cualquier cliente MCP) buscar anuncios de eBay a través de la Browse API oficial.

Pide "find me a mechanical keyboard under $100, buy-it-now only, free shipping" y el asistente puede ir a buscarlo de verdad.

eBay results for "mechanical keyboard" — showing 3 of about 41,208 matches

1. Keychron K8 Pro Wireless Mechanical Keyboard - Brown Switches — $79.99
   total $79.99 · free shipping · New · was $99.00 (19% off)
   seller keeb_supply · 99.6% positive (8421 ratings) · top rated, ships from US
   Item v1|335894120043|0 · https://www.ebay.com/itm/335894120043

2. Ducky One 3 TKL Mechanical Keyboard RGB Hot-Swappable — $84.50
   total $92.45 · $7.95 shipping · New
   seller pc_parts_direct · 98.9% positive (3310 ratings) · accepts offers
   Item v1|326770118254|0 · https://www.ebay.com/itm/326770118254

Lo que hace — y lo que deliberadamente no hace

Cada herramienta es de solo lectura. Este servidor busca y lee anuncios. No puede pujar, añadir al carrito, hacer un pedido ni gastar dinero. Cuando quieras comprar, te entrega un enlace al anuncio y tú mismo finalizas la compra.

Está construido sobre la API oficial Browse API de eBay — sin scraping, sin automatización de navegador, sin reutilización de cookies. No se romperá ante un cambio de diseño ni te hará incumplir las condiciones de uso de eBay.

Related MCP server: ebay-mcp

Herramientas

Dos cosas que conviene saber sobre search_ebay, porque son lo que eBay tiene y un catálogo de precio fijo no:

• buying_option filtra por auction, buy_it_now o accepts_offers.

• sort: "ending_soonest" — combinado con buying_option: "auction", así es como encuentras subastas que están a punto de cerrar.

Cómo obtener las claves de API

1. Inicia sesión en developer.ebay.com/my/keys.

2. Crea una aplicación y abre el conjunto de claves de Production.

3. Copia el App ID (Client ID) y el Cert ID (Client Secret).

Eso es todo. Este servidor utiliza el flujo OAuth de credenciales de cliente, por lo que no necesitas un token de usuario, una URI de redirección ni un "RuName".

Las cuentas de desarrollador nuevas pueden tener que completar la verificación de eBay antes de que se abra la página de claves; normalmente tarda aproximadamente un día hábil.

Instalación

git clone https://github.com/Kirat5690/shopping-mcp.git

cd shopping-mcp && npm install && npm run build

Conéctalo a un cliente

Claude Code

claude mcp add shopping --env EBAY_CLIENT_ID=your-app-id --env EBAY_CLIENT_SECRET=your-cert-id -- node /absolute/path/to/shopping-mcp/dist/index.js

Claude Desktop

Edita claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shopping": {
      "command": "node",
      "args": ["C:\\path\\to\\shopping-mcp\\dist\\index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your-app-id",
        "EBAY_CLIENT_SECRET": "your-cert-id",
        "EBAY_MARKETPLACE_ID": "EBAY_US"
      }
    }
  }
}

Reinicia el cliente y pídele que ejecute check_ebay_connection para confirmar que las credenciales funcionan.

Referencia de configuración

Notas sobre los números

• El precio final es lo que se ordena. La ordenación por precio utiliza el precio del artículo más el envío, de modo que un artículo barato con un envío caro no gana por una tecnicidad. La ordenación por precio de eBay no siempre hace esto.

• Algunos anuncios no tienen total. Cuando eBay indica el envío como calculado al finalizar la compra, no hay precio final hasta que se conoce una dirección de entrega, y el anuncio lo indica en lugar de adivinar.

• Sin conversión de divisas. Los precios se muestran en la moneda del propio marketplace, exactamente como los devuelve eBay.

• Los anuncios son ventas individuales, no entradas de catálogo. Dos resultados con títulos casi idénticos pueden diferir en estado, contenido del lote o región. Merece la pena comprobarlo antes de tratarlos como el mismo artículo.

• find_deals solo ve descuentos anunciados. Filtra por el precio tachado "was" de eBay, por lo que un anuncio realmente barato que nunca declaró un descuento no aparecerá.

Desarrollo

npm test

La suite se ejecuta sin ninguna credencial de eBay. Cubre la lógica de los importes y del precio final, el formato de salida y una prueba de protocolo MCP de extremo a extremo que arranca el servidor a través de stdio y ejercita el registro de herramientas, la validación de esquemas y las rutas de credenciales no configuradas.

npm run watch      # recompile on change
npm run typecheck  # types only, no emit

Estructura:

src/
  index.ts     server entry point and stdio wiring
  tools.ts     MCP tool definitions
  ebay.ts      Browse API client and OAuth token cache
  config.ts    environment parsing and marketplace table
  money.ts     price parsing, landed totals, ranking
  format.ts    human-readable output
  http.ts      fetch with timeout and retry

Una nota sobre el alcance

Las versiones anteriores también admitían Amazon a través de la Product Advertising API. Eso se eliminó en la v0.2.0: la PA-API requiere una cuenta de Amazon Associates aprobada, y Amazon revoca el acceso si la cuenta no realiza ventas que cumplan los requisitos — un listón demasiado alto para que la mayoría de la gente consiga poner el servidor en marcha.

El cliente de Amazon y su firma AWS SigV4 se conservan en el historial de git en la etiqueta v0.1.0-amazon por si tienes una cuenta aprobada y quieres recuperarlos.

Licencia

MIT — consulta LICENSE.

No está afiliado, respaldado ni patrocinado por eBay. Tu uso de la API de eBay se rige por el eBay API License Agreement.