shoplazza-mcp

Eine Python-Implementierung, die die Shoplazza OpenAPI (REST) als MCP (Model Context Protocol)-Dienst kapselt, sodass MCP-fähige Clients wie Claude, Cursor und DSH direkt Shoplazza-Shopdaten lesen und schreiben können (Produkte, Bestellungen, Kunden, Lagerbestand, Rabatte, Webhook-Abonnements usw.).

Das Endpunktverzeichnis (data/endpoints.json) wird von tools/scrape_endpoints.py automatisch aus der offiziellen Dokumentation extrahiert und deckt insgesamt 311 echte Endpunkte und 46 Ressourcengruppen der Version 2026-01 ab.

Funktionen

Installation

Anforderungen: Python ≥ 3.10, uv (empfohlen) oder pip.

cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）

Ohne uv:

python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .

Konfiguration

Bereitstellung von Anmeldedaten über Umgebungsvariablen (Schlüssel nicht in Code schreiben oder ins Repository committen):

# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token

* Entweder die Einzel-Shop-Konfiguration mit SHOPLAZZA_SHOP_DOMAIN + SHOPLAZZA_ACCESS_TOKEN oder die Multi-Shop-Konfiguration mit SHOPLAZZA_STORES angeben; wenn beide gesetzt sind, ist SHOPLAZZA_SHOP_DOMAIN der Standard-Shop.

Ein vollständiges Beispiel finden Sie in .env.example.

Multi-Shop-Verwendung

Nach der Konfiguration mehrerer Shops erhält jedes API-Tool im Dienst einen zusätzlichen optionalen Parameter shop_domain:

export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'

• Ohne shop_domain → Standard-Shop verwenden (SHOPLAZZA_SHOP_DOMAIN oder der erste Eintrag von STORES)

• Mit shop_domain → angegebenen Shop verwenden (bei unbekanntem Shop wird ein Fehler ausgegeben und die konfigurierten Shops aufgelistet)

• shoplazza_list_shops → alle konfigurierten Shops und den Standard-Shop des Dienstes anzeigen

• Jeder Shop hat ein eigenes Access-Token und einen eigenen Ratenbegrenzungs-Bucket (entspricht der offiziellen Regel der Begrenzung pro Shop); die Shops blockieren sich gegenseitig nicht.

Gesprächsbeispiel:

„Schau nach der Bestellanzahl des US-Shops heute und dann die Top-5-Produkte nach Umsatz im DE-Shop“ → Das Modell ruft shoplazza_orders / shoplazza_products jeweils mit shop_domain=us.myshoplazza.com und shop_domain=de.myshoplazza.com auf.

Claude-Desktop-Konfigurationsbeispiel (Multi-Shop):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}

Benötigte API-Berechtigungen (Scopes)

Wenn Sie eine App im Partnercenter erstellen/installieren oder einen Shop autorisieren, beantragen Sie nach dem Prinzip der geringsten Rechte nur die Scopes, die Sie benötigen. Für Datenabfragen verwenden Sie read_*, für Änderungen fügen Sie das gleichnamige write_* hinzu:

Empfohlene Kombination für reine Lese-/Betriebsszenarien: read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data. Nach der Autorisierung kann das Tool shoplazza_oauth_access_scopes aufgerufen werden, um die tatsächlich gewährten Scopes dieser Installation zu überprüfen. Die offizielle vollständige Zuordnung finden Sie unter Zugriffsberechtigungen.

So erhalten Sie ein Access-Token

• Öffentliche App: Verwenden Sie den OAuth-2.0-Autorisierungscode-Ablauf, tauschen Sie code gegen access_token (1 Jahr gültig, mit refresh_token erneuerbar).

• Privat / Interne Integration: Generieren Sie im Shoplazza-Adminbereich die entsprechenden Zugriffstoken für die App und den Shop.

Ausführen

stdio (lokaler MCP-Client, Standard)

uv run shoplazza-mcp

HTTP (Remote-Dienst)

uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765

Der Endpunktpfad ist standardmäßig /mcp und kann mit --http-path geändert werden.

MCP-Clients einbinden

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Cursor: Fügen Sie in den Einstellungen → MCP einen Server hinzu, Konfiguration siehe examples/mcp-cursor.json.

Remote-HTTP (beliebiger Client): Zeigen Sie die url auf http://host:8765/mcp.

Sie können es auch direkt ausführen (Debug: Tool-Liste und JSON-RPC-Interaktion anzeigen):

uv run mcp dev shoplazza-mcp

Anwendungsbeispiele (Dialog mit Claude / Cursor usw.)

• „Liste die 10 neuesten Bestellungen im Shop auf“

• „Prüfe den Lagerbestand des Produkts abcd-1234“

• „Storniere die Bestellung order-xxx mit dem Grund customer requested“

• „Erstelle einen Rabatt von 20 bei einem Mindestbestellwert von 100“

• „Welche API kann Rückerstattungen durchführen? Suche nach Endpunkten“ → Das Modell ruft shoplazza_search_endpoints("refund") auf und anschließend automatisch den entsprechenden Endpunkt.

Alle Antworten geben das ursprüngliche API-Paket zurück: {code, message, data, api_call_limit}; Listenantworten enthalten cursor / pre_cursor in data, zusammen mit den Parametern page_size / per_page für die Paginierung.

Entwicklung und Wartung

• tools/scrape_endpoints.py: Extrahiert aus der offiziellen Endpunkt-Dokumentationsseite und generiert data/endpoints.json (enthält für jeden Endpunkt Methode / Pfad / Parameter / Anforderungstextfelder / Antwortstruktur).

• Wartung: Um „häufig verwendete Tools“ hinzuzufügen oder zu entfernen, muss nur die Liste CURATED_SLUGS in shoplazza_mcp/tools.py geändert werden.

• scripts/smoke_test.py: Offline-Smoke-Test (stdio); scripts/http_smoke_test.py: HTTP-Smoke-Test.

Sicherheitshinweise

• Access-Token nur über Umgebungsvariablen / Client-Konfiguration injizieren, nicht in das Code-Repository schreiben.

• Der Dienst verwendet ausschließlich HTTPS (offiziell müssen alle Endpunkte nur über HTTPS erreichbar sein).

• Wenn der Dienst als HTTP-Service im externen Netzwerk bereitgestellt wird, platzieren Sie ihn im vertrauenswürdigen internen Netzwerk oder fügen Sie eine eigene Authentifizierung hinzu (z.B. Gateway, Firewall).

Lizenz

MIT