Ecommerce MCP Automation

Ein Beispiel für eine Claude Code + MCP-Integration: Shopify und Meta Ads als MCP-Tools bereitgestellt, plus ein Reporting-Agent, der beides in eine formatierte tägliche P&L- und Anzeigenleistungs-Tabelle zusammenführt – kein manuelles Kopieren und Einfügen zwischen den Plattformen.

Dies ist eine Demonstration, die anhand der öffentlichen Shopify Admin API und der Meta Marketing API-Dokumentation entwickelt wurde – nicht etwas, das ein echtes Geschäft betrieben hat. Es ist ein Clean-Room-Beispiel: echte Endpunkte, echte Authentifizierung, echte Paginierung, echte Fehlerbehandlung, frisch geschrieben, um genau zu zeigen, wie diese Art von Automatisierung aufgebaut wird. Es läuft durchgängig im Mock-Modus ohne Zugangsdaten (realistische Fixture-Daten als Stellvertreter für Live-Antworten) und wechselt pro Integration in den Live-Modus, sobald echte Zugangsdaten gesetzt sind – siehe So führen Sie es aus.

Der Shopify-Client wurde live gegen einen echten Shopify-Partners- Entwicklungs-Store (einen Sandbox-Store, kein Produktionsgeschäft) ausgeführt – echte Authentifizierung, eine echte Bestellung, echte API-Antworten. Dabei wurden zwei echte Nullability-Grenzfälle aufgedeckt und behoben (siehe Bekannte Vereinfachungen), die die Mock-Fixtures allein nicht abgedeckt hatten. Meta Ads läuft in diesem Repository standardmäßig gegen den Mock-Transport; der Client-Code ist genauso geschrieben und wechselt in den Live-Modus, sobald META_ACCESS_TOKEN/META_AD_ACCOUNT_ID gesetzt sind.

Was es macht

• Stellt Shopify-Bestellungen, Umsatz und COGS als MCP-Tools bereit (get_orders, get_daily_pnl)

• Stellt Meta-Ads-Ausgaben, Impressionen, Käufe und ROAS als MCP-Tools bereit (get_insights, get_daily_ad_performance)

• Führt einen Reporting-Agent (daily_report.py) aus, der beide gleichzeitig abruft und eine formatierte .xlsx-Arbeitsmappe mit Summary-, Orders- und Ad-Performance-Blättern schreibt

• Liefert eine Claude Code Skill mit, die den gesamten Workflow hinter einem natürlichsprachlichen Auslöser („Tagesbericht ausführen") kapselt

• Enthält eine eingecheckte Beispielausgabe, damit das Ergebnis sichtbar ist, ohne etwas auszuführen

Related MCP server: ads-mcp

Beispielausgabe

Gerenderte Vorschau des Summary-Tabs – öffnen Sie die tatsächlich generierte Arbeitsmappe für die Live-Datei (mit den Orders- und Ad-Performance-Blättern, Währungs-/ROAS-Formatierung und eingefrorenen Kopfzeilen).

Architektur

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

Die beiden API-Clients (clients/shopify_client.py, clients/meta_ads_client.py) sind echter Integrationscode – echte Endpunkt-URLs, echte Auth-Header, echte Paginierungsschleifen, echtes 429-Backoff. Das einzige, was sich zwischen Mock- und Live-Modus ändert, ist der HTTP-Transport (clients/http.py):

• Live: httpx.AsyncClient öffnet eine echte Verbindung zu Shopify / Meta.

• Mock: httpx.AsyncClient bekommt einen httpx.ASGITransport, der auf eine In-Process-FastAPI-App (fixtures/mock_api.py) zeigt, die realistische Fixture-Payloads ausliefert. Es wird kein Port gebunden, kein Subprozess gestartet – aber Anfragen durchlaufen weiterhin echtes HTTP/ASGI-Routing, Header und JSON-Kodierung.

Das bedeutet, dass der Client-Code, den ein Prüfer liest, derselbe Code ist, der gegen einen Live-Store laufen würde – kein Mock, der nur so aussieht. Siehe CLAUDE.md für die vollständigen Konventionen.

So führen Sie es aus

Mock-Modus (Standard – keine Zugangsdaten)

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

Führen Sie die Testsuite genauso aus, keine Einrichtung erforderlich:

pytest

Live-Modus

Kopieren Sie .env.example in .env und füllen Sie aus, was Sie haben – jede Integration wechselt unabhängig in den Live-Modus, sobald ihre eigenen Zugangsdaten vorhanden sind. So können Sie Shopify live ausführen, während Meta noch gemockt ist (oder umgekehrt):

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

Als MCP-Server (Claude Code / Claude Desktop)

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (.mcp.json für Claude Code oder die Konfigurationsdatei von Claude Desktop). Setzen Sie command direkt auf den venv-Interpreter des Projekts – MCP-Clients laden Ihr Shell-Profil nicht, daher sieht ein bloßes python kein aktiviertes venv:

{
  "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"
    }
  }
}

Fragen Sie Claude dann Dinge wie „Wie ist die heutige Shopify P&L?" oder „Hol mir die Meta-Werbeleistung von gestern" – Claude ruft die Tools direkt auf, standardmäßig im Mock-Modus.

Als Skill

skills/daily-report/SKILL.md kapselt den Workflow zur Berichtserstellung, sodass Claude Code ihn über einen natürlichsprachlichen Auslöser („Tagesbericht ausführen") ausführt, anstatt den genauen CLI-Befehl zu benötigen. Der Pfad für den vollständigen Bericht benötigt die obige MCP-Konfiguration überhaupt nicht – er führt daily_report.py direkt aus, das die Clients als normales Python aufruft, ganz ohne MCP. Die MCP-Konfiguration wird nur für den anderen Skill-Pfad benötigt: die Beantwortung einer einzelnen Kennzahl („Wie hoch ist der heutige ROAS?") durch den Aufruf von get_daily_pnl / get_daily_ad_performance als MCP-Tools, anstatt den gesamten Bericht auszuführen.

Projektstruktur

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

Bekannte Vereinfachungen

Hier dokumentiert statt versteckt, denn bei einem solchen Beispiel zählt Präzision mehr als Politur:

• COGS verwendet das Feld InventoryItem.cost von Shopify über den echten Two-Hop-Lookup (Variante → inventory_item_id → gebündelter inventory_items-Abruf) – Shopify gibt die Kosten nicht direkt auf der Bestellposition an. Sowohl cost als auch die Positions-sku sind in einem Live-Store nullable (ein Händler hat sie möglicherweise nie gesetzt) – gefunden durch Live-Tests gegen einen echten Dev-Store, nicht allein durch die Doku. Beide werden als Null-Kosten / fehlende SKU behandelt, anstatt einen Fehler zu werfen.

• Erstattete Bestellungen werden in daily_pnl() vollständig aus Umsatz/COGS/Bestellanzahl ausgeschlossen. Die Berücksichtigung von Teilerstattungen/Rücksendungen würde die Refund-Ressource erfordern – hier nicht im Umfang.

• Meta-Kaufattribuierung verwendet den Aktions-Typ purchase aus den Arrays actions/action_values mit dem Attributionsfenster, das für das Werbekonto konfiguriert ist – dieser Client überschreibt es nicht.

• Der Reporting-Agent ruft derzeit alle verfügbaren Bestellungen/Insights ab, anstatt nach Datumsbereich zu filtern; ein täglicher Produktions-Cron würde created_at_min/time_range für den Zieltag übergeben.

Lizenz

MIT – siehe LICENSE.