yampi-mcp

Ein MCP-Server, mit dem du mit deinem Yampi-Shop über Claude sprechen kannst – Bestellungen nachschlagen, Produkte anlegen, Bestände anpassen, Gutscheine und Angebote erstellen.

Jeder Händler betreibt seine eigene Kopie auf Cloudflare. Das ist kein Dienst: Niemand außer dir hat deine Zugangsdaten. Inoffiziell und nicht mit Yampi verbunden.

So funktioniert es

Yampi-Zugangsdaten gehören dem Benutzer, nicht dem Shop: Wenn du vier Shops unter einem Login betreibst, werden alle vier angezeigt. Du verbindest dich einmal und wählst den Shop bei jedem Befehl aus.

Related MCP server: MCP Shopify

Einrichtung

Du brauchst ein Cloudflare-Konto (der kostenlose Plan reicht) und Node installiert.

git clone https://github.com/Eduardo-Orsi/yampi-mcp && cd yampi-mcp
npm install
cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV   # paste the returned id into wrangler.jsonc
npx wrangler deploy

Füge in deinem Claude-Client (claude.ai, Desktop oder Code) einen benutzerdefinierten Connector hinzu, der auf https://yampi-mcp.<your-subdomain>.workers.dev/mcp zeigt.

Beim Verbinden fragt ein Bildschirm nach deinem User-Token und User-Secret-Key. Du findest sie im Yampi-Dashboard unter Perfil › Credenciais de API (Profil › API-Zugangsdaten). Das war’s – es gibt kein Passwort zu erstellen.

Verwendung

Sobald du verbunden bist, läuft es über ganz normale Unterhaltung:

„Wie viele bezahlte Bestellungen hat Shop X zwischen dem 1. und 15. Juni erhalten?“ „Erstelle ein Produkt namens Black T-Shirt, Marke Acme, SKU TS-BLACK-M, R$ 79,90, 20 auf Lager.“ „SKU TS-BLACK-M ist falsch bepreist – ändere das auf R$ 89,90 und reduziere den Bestand auf 5.“ „Welche Warenkörbe wurden diese Woche abgebrochen und wie hoch ist ihre Summe?“ „Erstelle einen 15-Prozent-Gutschein, gültig bis Monatsende, Mindestbestellwert R$ 100, 50 Verwendungen.“

Bei mehr als einem Shop auf dem Konto sag, welcher gemeint ist – die Tools verlangen das ausdrücklich, damit nichts im falschen Shop landet.

Was es tut

⚠️ Nicht gegen die Live-API validiert. Die anderen dreizehn wurden Ende-zu-Ende gegen einen echten Shop ausgeführt – ein Produkt anlegen, einen Preis ändern, Bestand schreiben, einen Gutschein ausstellen – und dabei sind ihre Feldnamen korrigiert worden. Diese beiden benötigen eine bestehende Bestellung, und der Test-Shop hatte keine. Die Endpunkte stimmen; der Request-Body stammt aus der Dokumentation, und bei jedem der anderen fünf Schreibvorgänge fehlte dort mindestens ein Pflichtfeld. Beim ersten Aufruf ist mit einer 422 zu rechnen – die Meldung nennt das fehlende Feld.

Was es bewusst nicht tut

Es storniert keine Bestellungen, erstattet keine Käufe und wechselt kein Zahlungsgateway. Kein Feature hinter einer Umgebungsvariable: Der Code existiert nicht. Das sind die irreversiblen Operationen der API, und weder Claude Desktop noch claude.ai unterstützt elicitation – der Server hat also keine Möglichkeit, wirklich nach einer Bestätigung zu fragen. Dass es den Code nicht gibt, ist die einzige Garantie, die nicht davon abhängt, dass jemand aufpasst.

Das Verbot wird an zwei Stellen durchgesetzt, beide durch Tests abgedeckt: beim Status-Alias (tools/write.ts) und an der Nahtstelle, durch die jede Anfrage läuft (yampi.ts). Begründung in docs/adr/0002.

Auch die Bestellverfolgung fällt aus: Yampi begrenzt diese Route auf 3 Anfragen pro Stunde, was das Tool nutzlos macht – zwei Aufrufe und der Agent hängt 20 Minuten lang fest.

Deine Zugangsdaten

• Gespeichert verschlüsselt (AES-GCM) in den OAuth-Grant-Props, in deinem KV.

• Der Schlüssel, der sie verschlüsselt, wird von einem Schlüssel umhüllt, der aus dem Access-Token abgeleitet wird, und KV enthält nur den Hash des Tokens. Ein KV-Leak allein gibt die Zugangsdaten nicht preis.

• Claude erhält sie nie: Es sieht immer nur ein opakes Token.

• Widerrufen bedeutet, den Grant zu löschen – andere Verbindungen funktionieren weiter.

/authorize ist öffentlich und validiert Zugangsdaten – das macht es praktisch zu einem Orakel zum Testen gestohlener Schlüssel. Daher die Begrenzung von 5 Versuchen pro IP pro Minute.

Um die Instanz auf bestimmte Shops zu beschränken:

npx wrangler secret put ALLOWED_STORES   # e.g. my-store,other-store

API-Limits

Yampi begrenzt pro Route und Minute: 30 req/min bei Produkten und SKUs, 120 bei Bestellabfragen, 30 bei Schreibvorgängen, 60 allgemein. Der Server nutzt z. B. include=, um Beziehungen in einem einzigen Aufruf statt mit N+1 zu holen, liest X-RateLimit-Remaining von jeder Antwort aus und warnt das Modell, wenn das Limit abläuft anstatt es es über eine 429 erfahren zu lassen.

Wenn etwas schiefgeht

403 bei allem, auch bei Lesezugriffen. Der Shop steht im Yampi-Dashboard auf active: false. Inaktive Shops lehnen jede Route ab. Reaktiviere den Shop und verbinde den Connector neu.

422 bei einem Schreibvorgang. Die Meldung benennt das exakte Feld, das Yampi abgelehnt hat – der Server reicht das ganze fehlerhafte errors-Objekt durch. Claude korrigiert sich beim nächsten Versuch meist selbst.

„Grant without credential“. Der Grant hat seine Eigenschaften verloren. Entferne den Connector und füge ihn wieder hinzu.

Zugangsdatenungen wechseln. Einfach neu verbinden: Ein neuer Grant ersetzt den alten. Um den Zugriff ohne Neuverbindenzubeenden, lösche den KV-Namensraum.

Ein Shop fehlt in der Liste. Entweder ist er inaktiv oder die Zugangsdaten erreisen ihn nicht. Führe describe_store aus, um zu sehen, was der Server sehen kann.

Yampi-API-Eigenheiten

Herausgefunden durch Tests gegen die Live-API. Alle davon können Stunden kosten, und keine ist aus der Dokumentation kans offensichtlich:

• Filter brauchen Array-Syntax. ?status_id=4 wird still ignoriert und gibt die gesamten Datenmenge zurück; ?status_id[]=4 filtert. Gleiches gilt für active[]. Ein Filter, der nicht filtert, ist schlimmer als kein Filter: Der Agent hat 55.000 Bestellungen geglaubt, er hätte die Daten des Juli.

• Daten verwenden ein eigenes Format: ?date=created_at:2026-06-01|2026-06-30. Alles andere führt zu 500 oder wird ignoriert.

• filters[...]filtert nicht. Es stellt die Antwort nur auf scroll_id-Paginierung um.

• /auth/me ist POST, nicht GET, und liefert jeden Shop der Zugangsdaten – benutzer und gehört dem Benutzer, nicht dem Shop.

• Der include-Parameter bei Bestellungen hat eine geschlossene Enum: items, customer, marketplace, status, statuses, shipping_address, promocode, transactions, comments, files, discounts, seller, labels. Es gibt kein payments.

• GET-Antworten werden bei Yampi 30 Minuten gecacht. In einem Agenten-Kontext ist das eine Lüge: Erstelle ein Produkt, bitte es zurück und du bekommst den vorherigen Stand. Dieser Server sendet ?skipCache=true bei jedem Lesevorgang.

• Bestand ist kein SKU-Feld. quantity ist bei einer SKU immer null – auch bei den echten SKUs eines aktiven Shops. Bestand lebt in /logistics/stocks (dem Lagerort) und wird mit der SKU über /catalog/skus/{id}/stocks verbunden. Und stock_id ist nicht die ID aus /logistics/warehouses, das ist eine ganz andere Ressource.

• Coupon-discount_type akzeptiert nur p oder v, nicht percentage gilt/fixed`.

• Coupon-Daten erfordern Y-m-d H:i:s. Das Datum allein verursacht eine 422.

• PUT /catalog/skus/{id} erfordert product_id und price_cost auch für ein partielles Update.

• Ein Produkt anzulegen erfordert simple, brand_id und skus.*.blocked_sale – none davon ist offensichtlich.

• Ein Shop mit active: false liefert bei allem eine 403, auch bei Lesezugriffen. Dieser Server filtert solche Shops beim Verbinden heraus, sodass dem Modell nie eine Option angeboten wird, die nur scheitern kann.

• 422-Antworten enthalten ein errors-Objekt, das das exakt fehlerhafte Feld benennt. Das lohnt sich an das Modell weiterzuleiten, statt nur den Statuscode zu zeigen – genau das ermöglicht die eigene Korrektur.

Entwicklung

npm test              # 32 unit tests, no network
npm run typecheck
npm run dev           # wrangler dev

Gegen deinen eigenen Shop testen

Die Unit-Test-Suite verwendet einen simulierten fetch und überprüft die Logik des Servers. Sie kann nicht merken, dass Yampi einen Endpunkt, einen Feldnamen oder eine Felder-Syntax ändert – und genau das ist während des Aufbaus dieses Projekts immer wieder passiert. Die andere Häfe ist durch eine Integration-Suite abgedeckt, die die Live-API nur lesend aufruft und nichts erstellt oder verändert:

cp .env.example .env    # fill in the alias and credentials of YOUR store
npm run test:integration

Sie prüft, dass die Shop-Erkennung funktioniert, dass Status-Aliase existieren, dass das Filtern nach Status wirklich filtert, dass das Datumsformat akzeptiert wird, dass include Beziehungen expandiert und dass die Quota-Header ankommen. Wenn einer davon fehlschlägt, hat sich die API geändert, und der Server beginnt zu lügen, bevor er anfängt zu brechen.

Die Architektur hat eine Regel: Kein Tool spricht HTTP. Alles läuft über src/yampi.ts. Das macht das Versprechen, gesperrte Routen nicht zu erreichen, überprüfbar – die gesamte Oberfläche passt in eine Datei.

Projektvokabeln in CONTEXT.md. Entscheidungen in docs/adr/.

Bekannte Einschränkungen

• Keine Bestellverfolgung und Yampios 3 req/h-Obergrenze sie unbrauchbar.

• Keine Banner, keine Regeln für kostenlosen Versand, keine Staffelrabatte und keine Combos.

• advance_order_status und add_order_comment wurden never against die Live-API ausgeführt.

• Der Bestand wird auf den ersten registrierten Lagerort des Shops geschrieben. Wer mehrere Lagerorte nutzt, muss defaultStockId() in src/tools/write.ts anpassen.

Mitwirken

Pull Requests sind willkommen. Forke das Repository, öffne einen PR gegen main, und CI lässt Typecheck und die Unit-Tests laufen. Für alles Größere einen Bugfix zuerst ein Issue öffnen.

Eine Sache wird unabhängig von der Qualität des Patches nicht eingebettet: alles, was eine Bestellung storniert, eine Zahlung erstattet oder ein Zahlungsgateway wechselt, einschließlich indirekter Wege. Diese Absenz ist der Sinn des Projekts – Begründung in ADR 0002.

Details in CONTRIBUTING.md. Ein Sicherheitsproblem gefunden? Öffne kein öffentliches Issue – siehe SECURITY.md.

Lizenz

MIT – siehe LICENSE.

Das Yampi-Logo in assets/ ist eine Marke von Yampi und wird hier nur verwendet, um zu kennzeichnen, mit welcher Plattform dieser Server kommuniziert. Es ist nicht von der MIT-Lizenz abgedeckt, und dieses Projekt ist weder mit Yampi verbunden noch von Yampi unterstützt.