Ecommerce MCP Automation

Una integración de ejemplo con Claude Code + MCP: Shopify y Meta Ads expuestos como herramientas MCP, además de un agente de informes que reúne ambos en una hoja de cálculo diaria formateada P&L + rendimiento publicitario — sin copiar y pegar manualmente entre plataformas.

Esta es una demostración construida a partir de la documentación pública de la API de Shopify Admin y la API de Meta Marketing — no es algo que haya operado un negocio real. Es una muestra de sala limpia: endpoints reales, autenticación real, paginación real, manejo de errores real, escrita desde cero para mostrar exactamente cómo se construye este tipo de automatización. Se ejecuta de principio a fin en modo simulado sin credenciales (datos de fixture realistas que sustituyen a las respuestas en vivo), y cambia a modo en vivo por integración en cuanto se establecen credenciales reales — consulte Cómo ejecutar.

El cliente de Shopify se ha ejecutado en vivo contra una tienda de desarrollo real de Shopify Partners (una tienda sandbox, no un negocio de producción) — autenticación real, un pedido real, respuestas reales de la API. Ese proceso sacó a la luz y corrigió dos casos límite reales de nulabilidad (consulte Simplificaciones conocidas) que los fixtures mock por sí solos no habían cubierto. Meta Ads se ejecuta contra el transporte mock por defecto en este repositorio; el código del cliente está escrito igual y cambia a en vivo en cuanto se establecen META_ACCESS_TOKEN/META_AD_ACCOUNT_ID.

Qué hace

• Expone pedidos, ingresos y COGS de Shopify como herramientas MCP (get_orders, get_daily_pnl)

• Expone el gasto, las impresiones, las compras y el ROAS de Meta Ads como herramientas MCP (get_insights, get_daily_ad_performance)

• Ejecuta un agente de informes (daily_report.py) que obtiene ambos simultáneamente y escribe un .xlsx con formato — hojas de Summary, Orders y Ad Performance

• Incluye una habilidad de Claude Code que envuelve todo el flujo de trabajo en un disparador en lenguaje natural ("ejecuta el informe diario")

• Incluye una salida de ejemplo ya confirmada en el repositorio para que el resultado sea visible sin ejecutar nada

Related MCP server: Ask AI

Salida de ejemplo

Vista previa renderizada de la pestaña Summary — abre el libro de trabajo generado real para ver el archivo en vivo (con las hojas Orders y Ad Performance, formato de moneda/ROAS y filas de cabecera congeladas).

Arquitectura

flowchart LR
    subgraph Shopify["Shopify Admin API"]
        SO[orders.json]
        SI[inventory_items.json]
    end
    subgraph Meta["Meta Marketing API"]
        MI[act_id/insights]
    end

    SO --> SC[shopify_client.py]
    SI --> SC
    MI --> MC[meta_ads_client.py]

    SC --> SS[shopify_server.py<br/>MCP tools]
    MC --> MS[meta_ads_server.py<br/>MCP tools]

    SC --> DR[daily_report.py]
    MC --> DR
    DR --> SPX[spreadsheet.py]
    SPX --> XLSX[(sample_daily_report.xlsx)]

    Mock[["mock_api.py<br/>(ASGITransport, in-process)"]] -.mock mode.-> SC
    Mock -.mock mode.-> MC

Los dos clientes de API (clients/shopify_client.py, clients/meta_ads_client.py) son código de integración genuino: URLs de endpoints reales, cabeceras de autenticación reales, bucles de paginación reales, backoff real de 429. Lo único que cambia entre el modo simulado y el modo en vivo es el transporte HTTP (clients/http.py):

• Live: httpx.AsyncClient abre una conexión real con Shopify / Meta.

• Mock: a httpx.AsyncClient se le da un httpx.ASGITransport apuntando a una aplicación FastAPI en proceso (fixtures/mock_api.py) que sirve payloads de fixture realistas. No se vincula ningún puerto, no se ejecuta ningún subproceso — pero las peticiones aún viajan mediante enrutamiento HTTP/ASGI genuino, cabeceras y codificación JSON.

Eso significa que el código de cliente que un revisor lee es el mismo código que se ejecutaría contra una tienda en vivo — no un mock disfrazado para parecerlo. Consulte CLAUDE.md para conocer todas las convenciones.

Cómo ejecutar

Modo simulado (por defecto — cero credenciales)

git clone <this-repo> && cd ecommerce-mcp-automation
python -m venv .venv && source .venv/bin/activate   # or: uv sync && source .venv/bin/activate
pip install -e ".[dev]"

python -m ecommerce_mcp.reporting.daily_report
# -> Wrote examples/sample_daily_report.xlsx

Ejecute la suite de pruebas de la misma manera, sin necesidad de configuración:

pytest

Modo en vivo

Copie .env.example a .env y rellene lo que tenga — cada integración pasa a en vivo de forma independiente en cuanto están presentes sus propias credenciales, de modo que puede ejecutar Shopify en vivo con Meta aún en modo simulado (o viceversa):

cp .env.example .env
# SHOPIFY_STORE_DOMAIN=your-dev-store.myshopify.com
# SHOPIFY_ACCESS_TOKEN=shpat_...          (Partners dev store -> custom app -> Admin API token)
# META_ACCESS_TOKEN=EAA...                (System User token, ads_read scope)
# META_AD_ACCOUNT_ID=act_1234567890

Como servidores MCP (Claude Code / Claude Desktop)

Añádalo a su configuración de MCP (.mcp.json para Claude Code, o el archivo de configuración de Claude Desktop). Apunte command directamente al intérprete del venv del proyecto — los clientes MCP no cargan su perfil de shell, por lo que un python a secas no verá un venv activado:

{
  "mcpServers": {
    "shopify": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.shopify_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    },
    "meta-ads": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.meta_ads_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    }
  }
}

Luego pregúntele a Claude cosas como "¿cuál es el P&L de Shopify hoy?" o "déme el rendimiento publicitario de Meta de ayer" — llamará a las herramientas directamente, en modo simulado por defecto.

Como habilidad

skills/daily-report/SKILL.md envuelve el flujo de trabajo de generación de informes para que Claude Code lo ejecute mediante un disparador en lenguaje natural ("ejecuta el informe diario") en lugar de necesitar el comando CLI exacto. La ruta del informe completo no necesita la configuración de MCP anterior en absoluto — ejecuta daily_report.py directamente, que llama a los clientes como Python puro, sin MCP involucrado. La configuración de MCP solo se necesita para la otra ruta del Skill: responder a una pregunta puntual de una sola métrica ("¿cuál es el ROAS de hoy?") llamando a get_daily_pnl / get_daily_ad_performance como herramientas MCP en lugar de ejecutar el informe completo.

Estructura del proyecto

src/ecommerce_mcp/
  clients/         Typed, async API clients (Shopify + Meta), transport-swappable
  mcp_servers/      MCP tool servers wrapping the clients
  reporting/        daily_report.py (orchestration) + spreadsheet.py (openpyxl)
  fixtures/         Realistic mock payloads + the in-process mock API app
skills/daily-report/ Claude Code Skill for the reporting workflow
tests/              pytest suite (all run against mock mode)
examples/           Committed sample .xlsx + README preview image

Simplificaciones conocidas

Documentadas aquí en lugar de ocultas, ya que la precisión importa más que el pulido en una muestra como esta:

• COGS utiliza el campo InventoryItem.cost de Shopify mediante la búsqueda real de dos saltos (variant → inventory_item_id → obtención por lotes de inventory_items) — Shopify no expone el coste directamente en la línea de pedido. Tanto cost como el sku de la línea de pedido son anulables en una tienda en vivo (un comercio puede no haberlos establecido nunca) — detectado mediante pruebas en vivo contra una tienda de desarrollo real, no a partir de la documentación únicamente. Ambos se manejan como coste cero / SKU ausente en lugar de dar error.

• Los pedidos reembolsados se excluyen por completo del recuento de ingresos/COGS/pedidos en daily_pnl(). La contabilización de reembolsos/devoluciones parciales requeriría el recurso Refund — fuera del alcance aquí.

• La atribución de compras de Meta utiliza el tipo de acción purchase de los arrays actions/action_values en cualquier ventana de atribución con la que la cuenta publicitaria esté configurada — este cliente no la anula.

• El agente de informes actualmente obtiene todos los pedidos/insights disponibles en lugar de filtrar por rango de fechas; un cron diario de producción pasaría created_at_min/time_range para el día objetivo.

Licencia

MIT — consulte LICENSE.