WooCommerce MCP open source: acceso de solo lectura a la tienda para agentes de IA

#WooCommerce MCP open source: acceso de solo lectura a la tienda para agentes de IA

En proyectos WooCommerce-a-ERP, la misma pregunta aparece en las llamadas de kickoff: ¿puede la IA simplemente consultar la tienda? La respuesta honesta es sí - si no puede romper nada. Esa restricción es la razón por la que publicamos woocommerce-mcp como open source: un servidor Model Context Protocol (MCP) pequeño que responde preguntas en vivo sobre productos, stock, pedidos, ventas y entradas a través de las REST API oficiales, con cero escrituras y sin plugin instalado en la tienda.

Este artículo es la guía de lanzamiento y operación del paquete publicado. Si necesitas diseñar un servidor a medida desde cero (incluyendo tools que mutan o despliegue en Workers), usa la guía compañera Building an MCP server for WooCommerce (aún en inglés). Para el programa comercial, consulta desarrollo de servidores MCP e integración WooCommerce ERP. El marco más amplio de agentes y compliance está en integración MCP e IA.

#TL;DR

• Paquete: @wppoland/woocommerce-mcp en npm (el binario CLI sigue llamándose woocommerce-mcp).
• Registry: io.github.wppoland/woocommerce-mcp en el MCP Registry oficial.
• Cinco tools de solo lectura sobre WooCommerce / WordPress REST - solo claves Read.
• Sin plugin en la tienda. MIT, TypeScript, Node 18+.
• Úsalo cuando los agentes necesiten hechos del catálogo y de pedidos; construye MCP a medida cuando necesites escrituras o tools específicas de ERP.

#Por qué enviamos un servidor MCP de solo lectura

MCP da a un host LLM (Claude Desktop, Cursor, un agente propio) una superficie tipada tools/list en lugar de obligar al modelo a inventar rutas /wp-json/wc/v3/. Eso es útil. También es peligroso si cada tool puede mutar inventario, reembolsos o datos de clientes.

En trabajo de sync ERP vemos dos modos de fallo con más frecuencia que los fallos ingeniosos de prompts:

1. Sobreventa en Black Friday / Cyber Monday porque una ruta de escritura compitió en carrera con el feed del almacén. En tiendas de moda B2C en la península ibérica, ese pico no es teórico: el tráfico del viernes negro y el lunes cibernético concentra pedidos mientras el ERP aún cierra líneas de stock del mayorista.
2. Cambios accidentales de estado cuando un agente, “por ayudar”, marcó pedidos como completados mientras depuraba.

El MCP de solo lectura no arregla un mal diseño de ERP. Elimina una clase de escrituras accidentales del plano del agente. La tienda sigue siendo el sistema de registro a través de WooCommerce REST. El agente solo pregunta.

Documentamos la decisión de protocolo en MCP vs REST: when each wins y la superficie de autenticación en MCP authentication patterns (ambas entradas aún en inglés). Este lanzamiento es el binario concreto que puedes instalar hoy. Si el debate comercial es “MCP en el plugin frente a chatbox en wp-admin”, el argumento de foso está en servidor MCP en plugin WordPress.

#Qué se publicó (julio 2026)

La versión 0.1.1 es el objetivo de instalación. La 0.1.0 existió brevemente como un stub fallido en el registro - una línea legacy conflictiva _auth en el ~/.npmrc local rompió ese publish. Ignora la 0.1.0.

#Por qué el nombre en npm es @wppoland/woocommerce-mcp

El nombre sin prefijo woocommerce-mcp está bloqueado en npm (E403) después de que otra parte lo unpublished. Publicamos como @wppoland/woocommerce-mcp. Usa ese nombre en npm install / npx. El campo bin en package.json sigue exponiendo el comando woocommerce-mcp, así que las configs de Claude Desktop y Cursor mantienen el mismo nombre de binario.

El mcpName en package.json es io.github.wppoland/woocommerce-mcp. Esa cadena debe coincidir con el campo name de server.json del MCP Registry para que la verificación de ownership funcione cuando publiques con el CLI oficial mcp-publisher.

#Superficie de tools

Todo se valida en el límite MCP y luego llama a REST. No hay ruta en este paquete que cree productos, actualice stock, reembolse pedidos o instale plugins.

#Preguntas que estas tools responden de verdad

• ¿Qué SKUs están a stock cero antes de una campaña de email o de un envío a clientes B2B?
• ¿Qué vendimos el mes pasado en términos netos que la tienda ya reporta?
• ¿Cuáles fueron los últimos veinte pedidos en processing?
• ¿La tienda es alcanzable con las claves que emitimos?

Esas son las preguntas que aparecen en los stand-ups de integración ERP. También son las preguntas que no requieren acceso de escritura. En operaciones con mayoristas en España o Latinoamérica de habla hispana, el equipo de atención suele abrir wp-admin solo para contestar “¿hay talla M en el SKU de la campaña?” - exactamente el caso de uso de list_products / get_product.

#Instalar y configurar

#Requisitos previos

• Node.js 18 o superior
• Una tienda WooCommerce en HTTPS
• Capacidad de crear claves REST API con permiso Read

#Instalación

npm install -g @wppoland/woocommerce-mcp
# or one-shot:
npx @wppoland/woocommerce-mcp

Desde el código fuente:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build

#Variables de entorno

Crea las claves en WooCommerce → Ajustes → Avanzado → REST API → Añadir clave. Permiso: Read. Si alguien te entrega Read/Write “por si acaso”, recházalo. El paquete no necesita scopes de escritura, y guardar scopes de escritura sin usar es un incidente esperando a un portátil comprometido.

search_posts funciona contra la REST API pública de WordPress sin claves Woo. Eso es útil para agentes de contenido; sigue sin ser motivo para exponer cookies de admin al host MCP.

#Esquema Claude Desktop / Cursor

Registra un servidor stdio que ejecute el binario con las tres variables de entorno. Las formas exactas de JSON varían según la versión del cliente; el invariante es: stdio, env inyectado por el host, sin secretos en el transcript del chat.

Tras conectar, pregunta algo falsable: “¿Cuál es el stock del SKU X?” Si el agente inventa un número sin una tool call, tu cliente no está cableado de verdad. Si llama a list_products o get_product y devuelve el valor de la tienda, el smoke test está hecho.

#Fragmento de ejemplo para Claude Desktop

Los formatos de config del cliente cambian; trata esto como una forma, no como un contrato eterno:

{
  "mcpServers": {
    "woocommerce-mcp": {
      "command": "woocommerce-mcp",
      "env": {
        "WP_URL": "https://shop.example.com",
        "WC_CONSUMER_KEY": "ck_replace_me",
        "WC_CONSUMER_SECRET": "cs_replace_me"
      }
    }
  }
}

Prefiere una ruta completa al binario desde npm root -g si el PATH del shell dentro de la app de escritorio es más pobre que el PATH de tu terminal. Cursor y otros hosts usan patrones similares de stdio + env.

#Solución de problemas de instalación

Si npm view @wppoland/woocommerce-mcp version devuelve 404 mientras npm access aún lista el paquete, estás en el estado de stub roto que vimos en 0.1.0. Sube la versión, elimina registry.npmjs.org/:_auth legacy de ~/.npmrc si está presente, y publica de nuevo. No digas a los clientes de la tienda que instalen una versión que no puedas npm pack.

#Modelo de seguridad (en lenguaje claro)

1. Las claves viven en el host MCP, no en la tienda como plugin y no en los pesos del modelo.
2. Solo permiso Read en la clave de WooCommerce.
3. Solo HTTPS para WP_URL.
4. Trata la máquina del cliente MCP como producción si guarda claves reales - el mismo listón que un almacén de secretos de CI.
5. Rota las claves cuando un portátil deja la empresa o termina un engagement de contratista.

MCP no resuelve la autenticación por magia. El tratamiento largo está en MCP authentication patterns. Para este paquete, el default conservador es stdio local con claves Read, no un endpoint HTTP MCP público en internet abierto.

#Notas de amenaza que aparecen en revisiones reales

• Robo de portátil: las claves Read filtran metadatos de catálogo y de pedidos. Eso sigue siendo relevante bajo RGPD / AEPD en España y bajo marcos equivalentes en otros mercados de habla hispana. Cifra el disco, usa claves de corta vida para demos, revoca en el offboarding.
• Prompt injection vía descripciones de producto: un título de producto malicioso no hará que este paquete escriba, pero puede dirigir el discurso del modelo. Mantén copia de catálogo no confiable fuera de automatizaciones de alto riesgo sin un humano en el bucle. En catálogos con fichas generadas por proveedores externos (textiles, electrónica), asume que el HTML de la descripción no es de confianza.
• Confused deputy en hosts MCP compartidos: un perfil de Claude Desktop con claves de la tienda A y la tienda B es un accidente esperando ocurrir. Perfiles separados o máquinas separadas. En agencias que gestionan varias tiendas desde la UE, esto no es teórico.
• Fuga en logs: algunos hosts registran argumentos de tools. Asume que SKUs e ids de pedido aparecerán en logs; configura la retención en consecuencia. Si el DPO pregunta por el registro de acceso a datos de pedidos, ten una respuesta antes del primer piloto.

Ninguna de esas es razón para evitar MCP. Son razones para tratar el host como producción.

#Dónde encaja en programas ERP e IA

El trabajo de WPPoland con clientes europeos a menudo conecta WooCommerce con APIs de mayoristas y ERPs. Los agentes entran en ese stack cuando los equipos de operaciones quieren respuestas en lenguaje natural sin abrir wp-admin. El MCP de solo lectura es la primera loncha segura:

• Comprobaciones pre-sync: “¿Ya estamos sin stock en los SKUs de la campaña?”
• Auditorías post-sync: “¿Los pedidos de ayer se parecen al conteo de facturas del ERP?”
• Ops de contenido: “¿Qué entradas mencionan la nueva colección?” vía search_posts

Cuando necesites que los agentes propongan pedidos o borradores de reembolso, sales de este paquete y construyes un servidor a medida con tools mutantes explícitas, claves de idempotencia y puertas de aprobación humana. Ese camino es la guía de construcción más typed catalogue tools with Zod. El servicio comercial que orquesta ese trabajo es desarrollo de servidores MCP; la pieza de datos comerciales es integración WooCommerce ERP.

Para tiendas ya ahogadas en plugin sprawl o deuda de temas hechos con IA, arregla Core Web Vitals y la verdad del inventario antes de añadir agentes. MCP no rescatará un TTFB de 1.8s ni un catálogo que discrepa del almacén. El trabajo de tienda y checkout sigue anclado en el desarrollador WooCommerce.

#Cómo difiere de experimentos MCP alojados en WordPress

WordPress.com y ecosistemas relacionados han explorado superficies MCP para hosting gestionado. Esos programas son valiosos, y no son el mismo artefacto que un servidor stdio self-hosted que apuntas a tus claves REST de WooCommerce. El MCP self-hosted mantiene credenciales y tráfico en infraestructura que eliges. El MCP alojado mantiene la comodidad en los términos del host. Elige a propósito; no asumas paridad de funcionalidades.

Glama y directorios MCP similares pueden indexar el repo de GitHub o la entrada del registry. Trata los directorios de terceros como descubrimiento, no como frontera de seguridad. La fuente de verdad para instalar sigue siendo npm + GitHub + el nombre oficial del MCP Registry.

Para entornos de prueba aislados con agentes, el ecosistema de playground también importa: ver WordPress Playground MCP y agentes de IA. Ese camino no sustituye claves Read de producción; evita mezclar ambos en el mismo perfil de cliente.

#Comparación: paquete open-source vs MCP a medida

#Notas de publicación para mantenedores

Si haces fork o publicas tu propio servidor MCP:

1. Pon mcpName en package.json coincidiendo con el namespace del registry (para auth de GitHub: io.github.<org>/<name>).
2. Mantén la description de server.json en 100 caracteres o menos - el registry oficial rechaza cadenas más largas con HTTP 422.
3. Usa el binario mcp-publisher de modelcontextprotocol/registry releases, no un paquete npm aleatorio llamado publisher.
4. Prefiere nombres npm bajo un @scope que controles; los nombres sin prefijo pueden quedar bloqueados permanentemente tras un unpublish.

Aprendimos el límite de description a la fuerza en el primer intento de publish al registry. Validar con mcp-publisher validate antes de publish ahorra un viaje de ida y vuelta.

#Checklist operativo

• @wppoland/[email protected] (o superior) instalado
• La clave de WooCommerce es solo Read
• WP_URL es HTTPS y coincide con la tienda a la que pertenecen las claves
• El cliente usa stdio (u otro transporte que hayas endurecido a propósito)
• El smoke test usa un SKU real y un rango de fechas real
• Los secretos no se pegan en tickets ni en logs de chat
• El equipo sabe que este paquete no puede reembolsar ni reponer stock - escala a humanos / ERP para escrituras

#Enlaces del cluster interno

• Ruta de construcción: Building an MCP server for WooCommerce
• Elección de protocolo: MCP vs REST
• Auth: MCP authentication patterns
• Tools tipadas: Writing typed catalogue tools with Zod for MCP
• Migración: Migrating an existing WordPress API to MCP
• Servicio: Desarrollo de servidores MCP
• Comercio: Integración WooCommerce ERP
• Programa IA: Integración MCP e IA
• Foso de plugin: Servidor MCP en plugin WordPress

#Notas de práctica desde trabajo con clientes

En una tienda B2C en España con picos de Black Friday (catálogo grande, precios B2B en ERP, fulfillment en Madrid), la demo que convenció a operaciones no fue un chatbot en el escaparate. Fue Claude Desktop en el portátil de ops respondiendo, antes del envío de la newsletter: “¿qué SKUs de campaña ya están a cero?”. La demo pasó la revisión del DPO solo porque MCP no podía “arreglar” el stock cuando el modelo proponía una escritura.

En un sync con mayorista que también abastece retailers en Valencia, la petición peligrosa fue “márcalos como completados si parecen pagados.” Exactamente la clase de tool que este paquete open-source se niega a ofrecer. El agente puede listar pedidos en processing; un humano o un job del ERP los completa. Esa frontera (leer sí, mutar no) fue la condición para aprobar el piloto.

Si tu tienda aún usa application passwords con capacidades completas para “scripts temporales”, rótalas antes de apuntar cualquier host MCP a producción. Las claves Read para este servidor son baratas de emitir y baratas de revocar. Un patrón que vemos en agencias hispanohablantes: claves Read distintas por entorno (staging vs producción) y por persona, nunca una clave compartida en un Notion interno.

Otro caso recurrente: tienda con TTFB alto por plugin de page builder y catálogo que discrepa del WMS. El agente devolvía stock Woo “correcto” según REST, y el almacén decía otra cosa. MCP hizo visible la mentira del sync; no la inventó. Arregla la integración ERP antes de pedir al agente que “confíe” en el número.

#Lo que no haremos en v0.x

• No hay tools de escritura en la rama default open-source.
• No hay plugin obligatorio en la tienda.
• No afirmamos que MCP sustituya WooCommerce REST para integraciones de partners.
• No hay precios concretos para trabajo de implementación - los proyectos se presupuestan de forma individual a través de desarrollo de servidores MCP.

Las feature requests que encajan en el mandato de solo lectura (resumen de reembolsos, estado de cupones, lookup de cliente sin dumps de PII) son conversación abierta en GitHub. Las feature requests del tipo “solo añade update_product” se cerrarán con un puntero a la guía de construcción a medida.

#Medir si la ruta del agente merece la pena

Antes de expandirte más allá de tools de solo lectura, mide tres cosas durante dos semanas:

1. Con qué frecuencia los humanos abren wp-admin solo para responder una pregunta de stock o de pedido. Si ese conteo es casi cero, MCP es una novedad. Si es diario, las tools de lectura se pagan solas en atención. En equipos de atención al cliente en castellano, suele ser “varios tickets al día” en temporada alta.
2. Con qué frecuencia esas respuestas discrepan del ERP. MCP mostrará la verdad de WooCommerce, no la del almacén. Si divergen, arregla el sync primero (integración WooCommerce ERP).
3. Con qué frecuencia alguien pide al agente que cambie estado. Esa frecuencia es tu señal de roadmap para un servidor mutante a medida - no una razón para debilitar este paquete.

Los programas GEO y AEO cuidan respuestas citables y estructuradas. Una tool call MCP que devuelve stock es más fiable que un modelo adivinando desde una página HTML raspada. Empareja la ruta del agente con entidades on-site y schema FAQ en tus páginas comerciales para que los sistemas de IA públicos y los agentes privados no inventen historias de producto distintas.

#Conclusión

@wppoland/woocommerce-mcp es la superficie MCP más pequeña que confiamos delante de una tienda WooCommerce en vivo: cinco tools de lectura, REST oficial debajo, MIT, publicado en npm y en el MCP Registry. Instálalo cuando los agentes necesiten hechos de la tienda. Construye un servidor a medida cuando los agentes necesiten acciones sobre la tienda.

Empieza aquí: https://www.npmjs.com/package/@wppoland/woocommerce-mcp - luego cablea claves Read, ejecuta una pregunta de smoke y mantén las escrituras fuera del camino del agente hasta que el programa esté listo para ellas.