@marketbasketanalysis/mcp

Ein MCP-Server, der jeder KI-Agentur Zugriff auf echte Co-Purchase-Intelligenz und Merchant-Ops-Werkzeuge aus der Bestellhistorie eines E-Commerce-Händlers gibt. 19 Tools in den Bereichen Discovery, Bundle, Insight, Replenishment, Merchant Ops und Advanced Mining. Funktioniert mit Claude Desktop, Claude Code, Cursor, Windsurf, Cline, dem OpenAI Agent SDK und jedem anderen Host, der das MCP-stdio-Protokoll spricht. Funktioniert für Händler auf Shopify, BigCommerce, WooCommerce, Magento und OroCommerce. Siehe „Plattformabdeckung“ weiter unten für die Tools, die die selbst gehosteten Backends erreichen.

Ein einziges npm-Paket bedient jeden Marktplatz. Der Server ist plattformagnostisch; er ist ein HTTP-Client, der über die öffentliche REST-API das MBA-Backend eines Stores aufruft. Sie richten den gesamten Server mit einem einzigen Schalter auf einen beliebigen Store aus (MBA_API_BASE, siehe unten). Die meisten Tools funktionieren auf allen fünf Plattformen; einige wenige hängen von einer Backend-Route ab, die noch nicht jede Plattform ausliefert. Die Marktplatzabdeckung pro Tool ist die Spalte „Marktplatz“ im Tool-Katalog.

Warum es das gibt

Wenn ein Kunde einen KI-Einkaufsagenten fragt: „Was passt zu dem Fitnessrucksack?“, sollte der Agent eine echte Antwort auf Basis der tatsächlichen Bestelldaten des Händlers geben – keine generische „Das könnte Ihnen auch gefallen“-Vermutung. Wenn ein Händler Claude fragt: „Woran sollte ich diese Woche arbeiten?“, sollte der Agent aus einem priorisierten Wochenplan schöpfen und nicht Aufgaben erfinden. Dieser Server macht beide Abläufe für jeden MCP-Host mit einer einzigen Konfigurationszeile verfügbar.

5-Zeilen-Installation (Claude Desktop)

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

Fügen Sie den Code in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ein, starten Sie Claude Desktop neu, und der marketbasketanalysis-Server erscheint mit allen 19 Tools in der Tool-Liste.

Zero-Installation: der gehostete Endpunkt

Der gleiche Server läuft gehostet unter https://mcp.marketbasketanalysis.com/mcp (MCP streamable HTTP). Nichts zu installieren; senden Sie Ihren Schlüssel als Bearer-Header statt als Umgebungsvariable:

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

Funktioniert mit jedem Remote-fähigen MCP-Client (Claude Code, Cursor, Smithery, benutzerdefinierte Agenten). Optionale Header: X-MBA-Base richtet den Server auf eine andere MBA-betriebene Ebene aus (z. B. https://bigcommerce.marketbasketanalysis.com); X-MBA-Platform spiegelt die Umgebungsvariable MBA_PLATFORM. Selbst gehostete WooCommerce- und Magento-Stores sind vom gehosteten Endpunkt aus bewusst nicht erreichbar; verwenden Sie die obige npx-Installation mit MBA_API_BASE, die auf Ihre eigene Site zeigt.

Den Server auf Ihren Store ausrichten (MBA_API_BASE)

Die Basis-URL ist pro Store konfiguriert. Standardmäßig spricht der Server mit dem gemeinsamen gehosteten Backend unter https://app.marketbasketanalysis.com. Wenn Ihre Daten woanders liegen – ein BigCommerce-Store, ein selbst gehostetes Backend oder eine Staging-Instanz – setzen Sie MBA_API_BASE, damit jedes Tool Ihre eigene Datenebene erreicht:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE ist der einzige Schalter, der den gesamten Server umrichtet; alle 19 Tools laufen darüber. Der Wert muss für nicht-lokale Hosts eine https://-URL sein (Loopback-, private, Link-Local- und Metadaten-Dienst-Hosts werden abgelehnt). Für die lokale Entwicklung gegen ein Backend auf localhost setzen Sie ALLOW_LOCAL_API_BASE=1, um eine http://localhost-Basis zuzulassen. Änderungen an Umgebungsvariablen werden beim Serverstart wirksam; starten Sie Ihren MCP-Host nach dem Bearbeiten des Werts neu.

MBA_API_BASE nach Plattform

Die Basis-URL ist pro Store konfiguriert. Shopify-, BigCommerce- und OroCommerce-Stores werden vom gemeinsamen gehosteten Backend bedient und verwenden daher den Standardwert. WooCommerce und Magento betreiben das Backend lokal in der Store-Installation; richten Sie den Server daher auf die eigene Domain des Stores aus:

Plattformabdeckung

Der Server erzeugt kanonische /api/v1/...-Pfade und schreibt sie pro Plattform um, weil WooCommerce und Magento das Backend innerhalb des Stores mit ihren eigenen REST-Konventionen betreiben (marketbasketanalysis/v1 bzw. V1/marketbasketanalysis).

10 der 19 Tools erreichen WooCommerce und Magento: die sechs, die von /recommendations abgeleitet sind (get_recommendations, get_bundle_for_cart, score_cross_sell, analyze_basket, propose_subscription_bundle, score_return_risk), plus find_substitutes, get_rationale, forecast_bundle und predict_reorder.

Die anderen 9 sind die Händler-Ops-Oberfläche: get_opportunities, triage_opportunity, get_weekly_plan, execute_weekly_plan_action, get_drift_alerts, get_forecast_alerts, explain_opportunity, explain_drift und mine_hui_itemsets. Diese Endpunkte existieren auf den selbst gehosteten Backends nicht. Ein Aufruf dort liefert eine klare „auf dieser Plattform nicht verfügbar“-Fehlermeldung, die den Endpunkt nennt, ohne Netzwerk-Round-Trip, statt eines undurchsichtigen 404.

Für die Schritt-für-Schritt-Installation (Speicherort der Config-Datei je Betriebssystem, wo Sie einen API-Schlüssel ausstellen, Fehlerbehebung):

• Claude Desktop: dist/mcp/claude-desktop-setup.md

• Cursor: dist/mcp/cursor-setup.md

• Windsurf: dist/mcp/windsurf-setup.md

Authentifizierung

Der Server liest MBA_API_KEY aus der Umgebung, die Ihr MCP-Host übergibt, und sendet ihn bei jeder Anfrage als Bearer-Token. So erhalten Sie einen Schlüssel:

1. Öffnen Sie die MarketBasketAnalysis-Verwaltung (Shopify-App-Drawer oder BigCommerce-/WooCommerce-/Magento-/OroCommerce-Verwaltung).

2. Klicken Sie im linken Navigationsbereich auf „API keys“.

3. Klicken Sie auf „Create key“, benennen Sie ihn und kopieren Sie den mba_live_-Wert (er wird nur einmal angezeigt).

Schlüssel sind pro Shop, widerrufbar und können über denselben Bildschirm rotiert werden. Es wird nur der SHA-256-Hash gespeichert; stellen Sie also einen neuen Schlüssel aus, falls ein Schlüssel durchsickert.

Das Authentifizierungsmodell unterscheidet sich je nach Marktplatz; der MCP-Server abstrahiert es, aber es ist wissenswert:

• Shopify, BigCommerce: Bearer mba_live_... direkt durchgereicht. Das ist der übliche Weg.

• WooCommerce: Bearer gegen einen von Woo ausgestellten Schlüssel, der für predict_reorder den Bereich customer_data tragen muss.

• Magento: Die Tools erreichen den Store über die Magento-REST-Oberfläche (/V1/marketbasketanalysis/* und /V1/mba/*); einige Routen sind auf der Store-Seite per Admin-Token / ACL abgesichert.

• OroCommerce: Der Store sitzt für /api/-Routen hinter der OAuth2-Firewall der Plattform; das gehostete Backend, an das der schlanke Client weiterleitet, ist das, was der MCP-Server tatsächlich aufruft; der mba_live_-Schlüssel gilt also weiterhin.

Tool-Katalog

19 Tools, organisiert in die vier Basket-AI-Agent-Rollen plus zwei operative Gruppen. Die Spalte Marktplatz gibt an, welche Backends die Route ausliefern, die das Tool aufruft – das ist nicht dasselbe wie die Backends, die dieser Server derzeit ERREICHEN kann: siehe „Plattformabdeckung“ oben. „Alle fünf“ bedeutet Shopify, BigCommerce, WooCommerce, Magento, OroCommerce.

Entdeckung

Bundle

Diese leiten alles von /recommendations ab (der Server setzt die Bundle-/Scoring-Logik clientseitig zusammen), benötigen also keine zusätzliche Backend-Route und funktionieren überall.

Erkenntnis

Ebenfalls von /recommendations abgeleitet, also universell.

Wiederauffüllung + Prognose

Händler-Ops

Diese rufen Bearer-/api/v1-Routen auf, die heute auf BigCommerce ausgeliefert werden. Shopify bedient Opportunities, Drift und den Wochenplan über seine eingebetteten Admin-Ansichten statt über eine /api/v1-Route, daher werden diese Tools gegen ein BigCommerce-Backend aufgelöst. Die eine Ausnahme ist /explain-opportunity, das jetzt auf BigCommerce und Shopify ausgeliefert wird; /explain-drift bleibt BigCommerce-exklusiv. Die Tools zeigen auf Plattformen ohne die Route einen sauberen Upstream-404.

Erweitertes Mining

Beispiel-Prompts pro Tool

Fügen Sie einen davon in einen Claude Desktop / Claude Code / Cursor Chat ein, nachdem Sie den Server eingerichtet haben:

• get_recommendations: "Verwenden Sie marketbasketanalysis, um herauszufinden, was Kunden außerdem mit dem Gym-Rucksack (Produkt 8472918765) kaufen."

• find_substitutes: "Das DSLR-Gehäuse ist ausverkauft. Was ist ein guter Ersatz?"

• get_rationale: "Warum wird die Wasserflasche zusammen mit dem Gym-Rucksack empfohlen?"

• get_bundle_for_cart: "Ich habe ein Kamera-Gehäuse, eine 32GB-SD-Karte und ein Stativ in meinem Warenkorb. Was fehlt wahrscheinlich, um daraus ein komplettes Set zu machen?"

• propose_subscription_bundle: "Erstelle ein monatliches Abo-Bundle für Kunde 9876."

• score_cross_sell: "Ist ein Reinigungsset ein gutes Cross-Selling für das DSLR-Kamera-Gehäuse?"

• score_return_risk: *"Wie hoch ist das Rückgaberisiko für das Kamera-Gehäuse + Objektiv

  • Stativ + Tasche-Bundle?"*

• analyze_basket: "Ich überlege, Kamera + Objektiv + SD-Karte + Tasche als Bundle anzubieten. Ist das auf Basis tatsächlicher Kundendaten ein starkes Bundle?"

• predict_reorder: "Was muss Acme Corp (Kunde 7654321) diese Woche nachbestellen?"

• forecast_bundle: "Prognostiziere das Bundle b-camera-kit für die nächsten 12 Wochen und empfehle eine Bestellmenge."

• get_weekly_plan: "Was steht auf meinem Wochenplan?"

• execute_weekly_plan_action: "Führe Aktion a-42 aus meinem Wochenplan aus, bestätigt."

• get_opportunities: "Zeig mir meine drei besten vorgeschlagenen Opportunities."

• explain_opportunity: "Warum ist Opportunity opp-17 ein gutes Cross-Selling?"

• triage_opportunity: "Aktiviere Opportunity opp-17, bestätigt."

• get_drift_alerts: "Driften irgendwelche meiner Regeln?"

• explain_drift: "Warum ist das Paar in Drift-Alert alert-7 abgedriftet?"

• get_forecast_alerts: "Welche Bundles sind von einem Stockout bedroht?"

• mine_hui_itemsets: "Extrahiere die Top-20-High-Utility-Itemsets aus diesen 90-Tage-Bestelldaten." (Plus-/Enterprise-Tarif)

Ausführliche Dokumentation zu den einzelnen Tools finden Sie im cookbook.

Umgebungsvariablen

Entwicklung

git clone https://github.com/48x-ai/marketbasketanalysis-mcp
cd marketbasketanalysis-mcp
npm install
npm run typecheck
npm test
npm run dev    # tsx-based local run
npm run build  # emit ./dist

Ein neues Tool hinzufügen

Jedes Tool ist ein eigenständiges Modul unter src/tools/. So fügen Sie eines hinzu:

1. Erstellen Sie src/tools/myNewTool.ts, das definition und handler exportiert. Orientieren Sie sich für ein einfaches GET an src/tools/getRecommendations.ts oder für ein POST mit Bestätigungs-Gate an src/tools/triageOpportunity.ts.

2. Registrieren Sie es in src/tools/index.ts, indem Sie das Modul importieren und zum allModules-Array hinzufügen.

3. Fügen Sie Tests in src/tools/myNewTool.test.ts hinzu, die Folgendes abdecken: Antwort bei fehlendem Schlüssel, Happy Path und mindestens einen Upstream-Fehlerpfad. Orientieren Sie sich an src/tools/findSubstitutes.test.ts.

4. Dokumentieren Sie es in der obigen Tabelle und in dist/mcp/smithery.yaml.

Distributionsartefakte

Das Verzeichnis dist/mcp/ im Monorepo-Root enthält die Installationsbeispiele (Claude Desktop, Cursor, Windsurf), die Smithery-YAML und die Einreichungsinhalte für den Anthropic-Marketplace. Die vollständige Struktur finden Sie in dist/mcp/README.md.

Veröffentlichung

Erhöhen Sie die Version in package.json (halten Sie server.json und src/index.ts synchron), führen Sie den Merge zu main durch, taggen Sie dann mcp-v$VERSION und pushen Sie den Tag. Der Workflow führt Typecheck, Test, Build und eine Prüfung auf Übereinstimmung von Tag und Version aus und führt dann mit dem Repository-Secret NPM_TOKEN den Befehl npm publish --access public --provenance aus. Für Rettungsläufe steht ein manueller workflow_dispatch-Auslöser zur Verfügung.

Die vollständige Operator-Checkliste, einschließlich der einmaligen Einrichtung von NPM_TOKEN und eines manuellen Publish-Fallback ohne CI, finden Sie in docs/RELEASE.md.

Fehlerbehebung

Für weiterführende Diagnosen siehe die jeweilige Setup-Dokumentation pro IDE unter dist/mcp/.

Lizenz

UNLICENSED, proprietär.