yampi-mcp

Un servidor MCP que te permite hablar con tu tienda de Yampi desde Claude: consulta pedidos, crea productos, ajusta el stock, crea cupones y ofertas.

Cada comerciante aloja su propia copia en Cloudflare. Esto no es un servicio: nadie tiene tus credenciales salvo tú. No oficial y sin afiliación con Yampi.

Cómo funciona

Una credencial de Yampi pertenece al usuario, no a la tienda: si gestionas cuatro tiendas con un mismo inicio de sesión, las cuatro aparecen. Te conectas una vez y eliges la tienda en cada comando.

Related MCP server: MCP Shopify

Configuración

Necesitas una cuenta de Cloudflare (el plan gratuito es suficiente) y Node instalado.

git clone https://github.com/Eduardo-Orsi/yampi-mcp && cd yampi-mcp
npm install
cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV   # paste the returned id into wrangler.jsonc
npx wrangler deploy

En tu cliente de Claude (claude.ai, Desktop o Code), añade un conector personalizado que apunte a https://yampi-mcp.<tu-subdominio>.workers.dev/mcp.

Al conectarte, una pantalla te pide tu User-Token y User-Secret-Key. Los encontrarás en el panel de Yampi en Perfil › Credenciais de API (Perfil › Credenciales de API). Eso es todo: no hay contraseña que crear.

Uso

Una vez conectado, es conversación normal:

"¿Cuántos pedidos pagados recibió la tienda X entre el 1 y el 15 de junio?" "Crea un producto llamado Camiseta Negra, marca Acme, SKU TS-BLACK-M, R$ 79,90, 20 en stock." "El SKU TS-BLACK-M tiene un precio incorrecto: cámbialo a R$ 89,90 y baja el stock a 5." "¿Qué carritos se abandonaron esta semana y cuánto suman?" "Crea un cupón del 15% válido hasta fin de mes, mínimo R$ 100, 50 usos."

Si hay más de una tienda en la cuenta, indica cuál: las herramientas lo exigen explícitamente para que nada se escriba en la tienda equivocada.

Qué hace

⚠️ No validadas contra la API en vivo. Las otras trece se probaron de extremo a extremo contra una tienda real —creando un producto, cambiando un precio, escribiendo stock, emitiendo un cupón— y sus nombres de campo salieron de ese proceso corregidos. Estas dos necesitan un pedido existente, y la tienda de prueba no tenía ninguno. Los endpoints son correctos; el cuerpo de la petición proviene de la documentación, que resultó omitir al menos un campo obligatorio en cada una de las otras cinco escrituras. Espera un 422 en la primera llamada: el mensaje indicará el campo que falta.

Lo que deliberadamente no hace

No cancela pedidos, no reembolsa compras ni cambia de pasarela de pago. No es una función oculta tras una variable de entorno: el código no existe. Son las operaciones irreversibles de la API, y ni Claude Desktop ni claude.ai admiten elicitation, lo que significa que el servidor no tiene forma de pedir confirmación de verdad. La ausencia es la única garantía que no depende de que alguien preste atención.

La prohibición se aplica en dos lugares, ambos cubiertos por pruebas: en el alias de estado (tools/write.ts) y en el punto por el que pasa cada petición (yampi.ts). Justificación en docs/adr/0002.

El seguimiento de pedidos también queda fuera: Yampi limita esa ruta a 3 peticiones por hora, lo que hace que la herramienta sea inútil en la práctica: dos llamadas y el agente queda bloqueado durante 20 minutos.

Tus credenciales

• Se almacenan cifradas (AES-GCM) en las propiedades de la concesión OAuth, dentro de tu KV.

• La clave que las cifra está envuelta por una clave derivada del token de acceso, y KV solo guarda el hash del token. Una fuga de KV por sí sola no abre las credenciales.

• Claude nunca las recibe: solo ve un token opaco.

• Revocar significa eliminar la concesión: las demás conexiones siguen funcionando.

/authorize es público y valida credenciales, lo que técnicamente lo convierte en un oráculo para probar claves robadas. De ahí el límite de 5 intentos por IP por minuto.

Para restringir la instancia a tiendas específicas:

npx wrangler secret put ALLOWED_STORES   # e.g. my-store,other-store

Límites de la API

Yampi limita por ruta y por minuto: 30 req/min en productos y SKUs, 120 en lecturas de pedidos, 30 en escrituras, 60 en general. El servidor usa include= para traer las relaciones en una sola llamada en lugar de N+1, lee X-RateLimit-Remaining de cada respuesta y avisa al modelo cuando la cuota se está agotando, en lugar de dejar que lo descubra con un 429.

Cuando algo sale mal

403 en todo, incluidas las lecturas. La tienda está con active: false en el panel de Yampi. Las tiendas inactivas rechazan todas las rutas. Reactívala y vuelve a conectar el conector.

422 en una escritura. El mensaje indica el campo exacto que Yampi rechazó: el servidor reenvía el objeto errors completo. Claude suele corregirse solo en el siguiente intento.

"Grant without credential" (Concesión sin credencial). La concesión perdió sus propiedades. Elimina el conector y vuelve a añadirlo.

Cambio de credenciales. Solo hay que reconectar: una concesión nueva reemplaza a la anterior. Para cortar el acceso sin reconectar, elimina el namespace de KV.

Falta una tienda en la lista. O está inactiva, o la credencial no llega a ella. Ejecuta describe_store para ver qué ve el servidor.

Peculiaridades de la API de Yampi

Descubiertas probando contra la API en vivo. Todas pueden hacerte perder horas y ninguna está clara en la documentación:

• Los filtros necesitan sintaxis de array. ?status_id=4 se ignora silenciosamente y devuelve el conjunto completo de datos; ?status_id[]=4 filtra. Lo mismo con active[]. Un filtro que no filtra es peor que ningún filtro: el agente resume 55.000 pedidos creyendo que ha visto los de julio.

• Las fechas usan un formato propio: ?date=created_at:2026-06-01|2026-06-30. Cualquier otra cosa devuelve 500 o se ignora.

• filters[...] no filtra. Solo cambia la respuesta a paginación con scroll_id.

• /auth/me es POST, no GET, y devuelve todas las tiendas de la credencial, porque la credencial pertenece al usuario, no a la tienda.

• El include de pedidos tiene un enum cerrado: items, customer, marketplace, status, statuses, shipping_address, promocode, transactions, comments, files, discounts, seller, labels. No existe payments.

• Las respuestas GET se cachean durante 30 minutos en el lado de Yampi. En un contexto de agente eso miente: crea un producto, pide leerlo y obtienes el estado anterior. Este servidor envía ?skipCache=true en cada lectura.

• El stock no es un campo del SKU. quantity en un SKU siempre es null, incluso en los SKUs reales de una tienda en vivo. El stock vive en /logistics/stocks (la ubicación de stock) unido al SKU en /catalog/skus/{id}/stocks. Y stock_id no es el id de /logistics/warehouses, que es un recurso completamente distinto.

• El discount_type de los cupones solo acepta p o v, no percentage/fixed.

• Las fechas de los cupones requieren Y-m-d H:i:s. Solo la fecha devuelve 422.

• PUT /catalog/skus/{id} requiere product_id y price_cost incluso para una actualización parcial.

• Crear un producto requiere simple, brand_id y skus.*.blocked_sale, ninguno de ellos evidente.

• Una tienda con active: false devuelve 403 en todo, incluidas las lecturas. Este servidor filtra esas tiendas al conectar, para que el modelo nunca reciba una opción que solo puede fallar.

• Las respuestas 422 llevan un objeto errors que indica el campo exacto que falló. Merece la pena reenviarlo al modelo en lugar de mostrar solo el código de estado: es lo que le permite corregirse.

Desarrollo

npm test              # 32 unit tests, no network
npm run typecheck
npm run dev           # wrangler dev

Probar contra tu propia tienda

La suite de pruebas unitarias usa un fetch simulado y demuestra la lógica del servidor. No puede detectar que Yampi cambie un endpoint, un nombre de campo o una sintaxis de filtro, y eso ocurrió en repetidas ocasiones mientras se construía este proyecto. Esa otra mitad la cubre una suite de integración que golpea la API en vivo, solo lectura, sin crear ni cambiar nada:

cp .env.example .env    # fill in the alias and credentials of YOUR store
npm run test:integration

Comprueba que el descubrimiento de tiendas funciona, que los alias de estado existen, que filtrar por estado filtra de verdad, que el formato de fecha se acepta, que include expande las relaciones y que llegan las cabeceras de cuota. Si una falla, la API ha cambiado y el servidor empezará a mentir antes de empezar a romperse.

La arquitectura tiene una regla: ninguna herramienta habla HTTP. Todo pasa por src/yampi.ts. Eso es lo que hace auditable la promesa de "no llega a las rutas prohibidas": toda la superficie cabe en un solo archivo.

Vocabulario del proyecto en CONTEXT.md. Decisiones en docs/adr/.

Limitaciones conocidas

• Sin seguimiento de pedidos (el límite de 3 req/h de Yampi lo hace inutilizable).

• Sin banners, reglas de envío gratuito, descuentos progresivos ni combos.

• advance_order_status y add_order_comment nunca se ejecutaron contra la API en vivo.

• El stock se escribe en la primera ubicación de stock registrada de la tienda. Quien use varias ubicaciones debe ajustar defaultStockId() en src/tools/write.ts.

Contribuciones

Las pull requests son bienvenidas. Haz un fork, abre una PR contra main, y CI ejecuta el typecheck y las pruebas unitarias. Para algo más grande que una corrección de errores, abre primero un issue.

Hay una cosa que no se fusionará sin importar la calidad del parche: cualquier cosa que cancele un pedido, reembolse una compra o cambie de pasarela de pago, incluidas las rutas indirectas. Esa ausencia es el sentido del proyecto: razonamiento en ADR 0002.

Detalles en CONTRIBUTING.md. ¿Has encontrado un problema de seguridad? No abras un issue público: consulta SECURITY.md.

Licencia

MIT: consulta LICENSE.

El logotipo de Yampi en assets/ es una marca comercial de Yampi, utilizado aquí únicamente para identificar con qué plataforma se comunica este servidor. No está cubierto por la licencia MIT y este proyecto no está afiliado a Yampi ni cuenta con su respaldo.