MCP WooCommerce

Servidor MCP + Bot de Telegram para gestionar tu tienda WooCommerce con IA.

Dos modos de uso:

• MCP Server — Conectá directamente desde Claude Desktop o Claude Code
• Bot de Telegram — Gestioná tu tienda desde Telegram con lenguaje natural y voz

Features

• 13 herramientas para gestionar productos, pedidos, clientes y reportes
• Dual LLM — Un modelo para consultas (rápido/barato) y otro para edición (preciso)
• Soporte de voz — Enviá audios por Telegram, se transcriben con Whisper
• Multi-proveedor — Soporta Claude, OpenAI (GPT) y Gemini como LLM
• Deploy en Cloudflare Workers — Gratis, siempre activo, sin servidor

Herramientas disponibles

Categoría	Herramienta	Descripción
Productos	list_products	Listar con filtros (búsqueda, categoría, estado)
	get_product	Detalle de un producto por ID
	create_product	Crear producto nuevo
	update_product	Editar precio, stock, descripción, estado
	delete_product	Eliminar producto
Pedidos	list_orders	Pedidos recientes con filtros
	get_order	Detalle de un pedido
	update_order_status	Cambiar estado del pedido
Clientes	list_customers	Buscar por nombre o email
	get_customer	Detalle y historial de compras
Reportes	sales_report	Ventas del día/semana/mes
	top_products	Productos más vendidos
	revenue_summary	Resumen de ingresos completo

Requisitos previos

• Node.js 18+
• Cuenta de WooCommerce con API REST habilitada
• Para Telegram: Bot token de @BotFather
• Para deploy: Cuenta de Cloudflare (gratis)
• API key de al menos un proveedor LLM (OpenAI, Anthropic o Google)

Instalación

git clone https://github.com/tu-usuario/mcp-woocommerce.git
cd mcp-woocommerce
npm install

Obtener credenciales de WooCommerce

1. En tu panel de WordPress: WooCommerce → Ajustes → Avanzado → REST API
2. Click en "Agregar clave"
3. Descripción: MCP Bot
4. Permisos: Lectura/Escritura
5. Click en "Generar clave API"
6. Guardá el Consumer Key (ck_...) y Consumer Secret (cs_...)

---

Modo 1: MCP Server (Claude Desktop / Claude Code)

Conectá las herramientas de WooCommerce directamente a Claude sin intermediarios.

Configuración en Claude Desktop

Editá tu archivo de configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["tsx", "src/mcp-server.ts"],
      "cwd": "/ruta/a/mcp-woocommerce",
      "env": {
        "WC_URL": "https://tu-tienda.com",
        "WC_CONSUMER_KEY": "ck_xxxxxxxxxxxxxxxxxxxxx",
        "WC_CONSUMER_SECRET": "cs_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Configuración en Claude Code

claude mcp add woocommerce \
  -e WC_URL=https://tu-tienda.com \
  -e WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxx \
  -e WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxx \
  -- npx tsx src/mcp-server.ts

Probar localmente

WC_URL=https://tu-tienda.com \
WC_CONSUMER_KEY=ck_xxx \
WC_CONSUMER_SECRET=cs_xxx \
npm run mcp

---

Modo 2: Bot de Telegram

Bot interactivo que responde mensajes de texto y voz usando IA.

Arquitectura

Telegram (vos) → Cloudflare Worker (webhook) → LLM (tool calling) → WooCommerce API
       ← respuesta formateada ← datos/confirmación ←

Crear bot de Telegram

1. Abrí @BotFather en Telegram
2. Enviá /newbot y seguí las instrucciones
3. Guardá el token que te da
4. Mandá un mensaje a tu bot nuevo (un "hola")
5. Visitá https://api.telegram.org/bot<TOKEN>/getUpdates para obtener tu Chat ID

Variables de entorno

Copiá el archivo de ejemplo:

cp .dev.vars.example .dev.vars

Editá .dev.vars con tus credenciales:

# Telegram
TELEGRAM_BOT_TOKEN=tu-token
TELEGRAM_CHAT_ID=tu-chat-id

# WooCommerce
WC_URL=https://tu-tienda.com
WC_CONSUMER_KEY=ck_xxx
WC_CONSUMER_SECRET=cs_xxx

# LLM - Modo simple (un solo proveedor)
LLM_PROVIDER=openai
LLM_API_KEY=sk-xxx

# LLM - Modo dual (recomendado)
LLM_QUERY_PROVIDER=openai      # Para consultas: rápido y barato
LLM_QUERY_API_KEY=sk-xxx
LLM_EDIT_PROVIDER=claude       # Para edición: preciso y confiable
LLM_EDIT_API_KEY=sk-ant-xxx

Sistema Dual LLM

El bot puede usar dos LLMs diferentes según el tipo de operación:

Tipo	Proveedor recomendado	Modelo	Para qué
Consultas	OpenAI	gpt-4o-mini / gpt-5.3	Listar, buscar, reportes
Edición	Anthropic	claude-sonnet-4	Crear, actualizar, eliminar

El routing es automático: detecta si tu mensaje contiene palabras como "crear", "editar", "cambiar precio", etc.

Si configurás solo LLM_PROVIDER y LLM_API_KEY, usa un único modelo para todo.

Soporte de voz (Whisper)

Enviá un mensaje de voz al bot y:

1. Se descarga el audio de Telegram
2. Se transcribe con OpenAI Whisper (gpt-4o-mini-transcribe)
3. Te muestra qué entendió
4. Procesa la consulta normalmente

Requiere LLM_QUERY_API_KEY con una API key de OpenAI (Whisper usa la misma key).

Proveedores LLM soportados

Proveedor	Valor de config	Modelos
OpenAI	openai	gpt-4o, gpt-4o-mini, gpt-5.3-chat-latest
Anthropic	claude	claude-sonnet-4, claude-haiku-4
Google	gemini	gemini-2.0-flash

Deploy en Cloudflare Workers

1. Login en Cloudflare

npx wrangler login

2. Deploy

npm run deploy

3. Configurar secrets

npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put TELEGRAM_CHAT_ID
npx wrangler secret put WC_URL
npx wrangler secret put WC_CONSUMER_KEY
npx wrangler secret put WC_CONSUMER_SECRET
npx wrangler secret put LLM_QUERY_PROVIDER
npx wrangler secret put LLM_QUERY_API_KEY
npx wrangler secret put LLM_EDIT_PROVIDER
npx wrangler secret put LLM_EDIT_API_KEY

4. Configurar webhook de Telegram

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<tu-worker>.workers.dev/webhook"

O con el script incluido:

TELEGRAM_BOT_TOKEN=xxx WORKER_URL=https://tu-worker.workers.dev npx tsx scripts/set-webhook.ts

Desarrollo local

npm run dev

Usa las variables de .dev.vars automáticamente.

---

Estructura del proyecto

mcp-woocommerce/
├── src/
│   ├── index.ts              # Entry point Cloudflare Worker
│   ├── mcp-server.ts         # MCP Server (Claude Desktop/Code)
│   ├── bot/
│   │   ├── handler.ts        # Bot Telegram + webhook + tool execution
│   │   └── auth.ts           # Validación de Chat ID
│   ├── llm/
│   │   ├── provider.ts       # Abstracción LLM (Claude/OpenAI/Gemini)
│   │   └── tools.ts          # Definición de herramientas
│   ├── woocommerce/
│   │   ├── client.ts         # Cliente REST API v3
│   │   ├── products.ts       # Operaciones de productos
│   │   ├── orders.ts         # Operaciones de pedidos
│   │   ├── customers.ts      # Operaciones de clientes
│   │   └── reports.ts        # Reportes y análisis
│   └── utils/
│       └── formatter.ts      # Formateo para Telegram
├── scripts/
│   └── set-webhook.ts        # Script para configurar webhook
├── wrangler.toml              # Config Cloudflare Workers
├── .dev.vars.example          # Ejemplo de variables de entorno
└── package.json

Seguridad

• Las API keys se almacenan como secrets encriptados en Cloudflare (nunca en el código)
• El bot solo responde a tu Chat ID configurado
• El MCP server lee credenciales de variables de entorno (nunca hardcodeadas)
• El archivo .dev.vars está en .gitignore

Limitaciones (Cloudflare Workers free tier)

• Timeout de 30 segundos por request
• 100,000 requests/día
• Sin estado persistente entre requests (stateless)
• Webhook mode obligatorio (no polling)

Licencia

MIT