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

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:

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

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