WandPad Etsy MCP-Server

WandPad Etsy MCP-Server

Ein lokaler MCP-Server (Model Context Protocol), über den Claude auf den Etsy-Shop WandPad zugreifen kann - Shopdaten, Listings, Bestände, Varianten, Bestellungen lesen, und (optional, explizit freizuschalten) Listings anlegen und bearbeiten. Verwendet die offizielle Etsy Open API v3 mit OAuth 2.0 (Authorization Code Flow + PKCE).

Stufe 1: Lesezugriff. Immer aktiv, unabhängig von jeder Konfiguration.

Stufe 2: Schreibzugriff. Standardmäßig deaktiviert (ETSY_WRITE_ENABLED=false). Erst nach bewusster lokaler Freischaltung nutzbar - und selbst dann verlangt jede echte Änderung eine explizite Vorschau (dry_run) und Bestätigung (confirm/confirm_bulk) im Chat. Es gibt keine Funktion, die Listings löscht - das wird es nie geben.

Inhalt

• Zweck der Integration
• Voraussetzungen
• Installation
• Etsy Developer App
• Callback-URL
• Umgebungsvariablen
• Etsy-Scopes
• OAuth-Anmeldung
• Start des MCP-Servers
• Verbindung zu Claude Desktop
• Verbindung zu Claude Code
• Erster Lesetest
• Verfügbare Tools
• Tokens erneuern
• Tokens zurücksetzen (Logout)
• Fehlerbehebung
• Datenschutz
• Sicherheitsregeln
• Bekannte Einschränkungen der Etsy API
• Schreibmodus aktivieren (Stufe 2)
• Gehostetes Deployment für Cowork-Agenten
• Vollständige Deinstallation

Zweck der Integration

WandPad® verkauft individuell gefertigte, 3D-gedruckte Tablet-Wandhalterungen über Etsy. Dieser MCP-Server gibt Claude strukturierten, lesenden Zugriff auf den Shop, damit Claude beim Analysieren von Sortiment, Preisen, Beständen, Tags und Bestellungen helfen kann - ohne selbst etwas am Shop zu verändern.

Voraussetzungen

• macOS
• Node.js 20 oder neuer (LTS empfohlen) - geprüft mit Node 24
• openssl im PATH (auf macOS vorinstalliert) - wird für ein lokales TLS-Zertifikat benötigt
• Eine genehmigte Etsy Developer App mit Produktionszugriff

Bereits erfolgte Produktionsfreigabe

Etsy hat die Nutzung der Open API v3 in der Produktionsumgebung (nicht Sandbox) für diese Integration bereits genehmigt. Der Server verwendet ausschließlich echte Etsy-Endpunkte (https://api.etsy.com/v3/application/...), keine Testumgebung.

Installation

cd "/Users/Dodo/Library/Mobile Documents/com~apple~CloudDocs/Documents/Claude Code"
npm install
npm run build
npm test

npm test führt die Tests für sicherheitskritische Funktionen aus (PKCE, Token-Speicher, PII-Redaktion, Audit-Log-Schutz, Eingabevalidierung, Callback-URL-Prüfung).

Etsy Developer App

Deine App-Zugangsdaten findest du unter etsy.com/developers/your-apps. Wichtig: Der API-Key-Status muss "Active" (bzw. "Personal Access") sein, nicht "Pending" - sonst lehnt Etsy jede Anfrage mit HTTP 403 ab.

Etsy zeigt das Shared Secret im Dashboard teils verkürzt an. Klicke explizit auf das Augen-Symbol, um den vollständigen Wert aufzudecken, bevor du ihn kopierst.

Callback-URL

Etsy verlangt für die OAuth-Callback-URL zwingend ein https://-Prefix - auch für localhost. Eine reine http://localhost:3000/...-Adresse wird von Etsy abgelehnt (offizielle Doku: "The URL must have the https:// prefix or the request will fail", keine Ausnahme für localhost dokumentiert).

In deiner Etsy-App muss deshalb exakt folgende Callback-URL eingetragen sein:

https://localhost:3000/oauth/callback

Da hierfür TLS notwendig ist, erzeugt der Server beim ersten Login automatisch ein selbstsigniertes Zertifikat für localhost (per openssl, liegt danach unter .secrets/localhost-*.pem). Der Browser zeigt beim Login deshalb einmalig eine Zertifikatswarnung ("Verbindung ist nicht privat") - für localhost unbedenklich, einfach fortfahren/bestätigen.

Umgebungsvariablen

Kopiere .env.example zu .env (falls noch nicht geschehen) und trage deine Werte ein:

.env und alles unter .secrets/ sind in .gitignore eingetragen und werden nie committet.

Etsy-Scopes

Der Login fordert folgende Scopes an:

• shops_r - Shop-Stammdaten, Ankündigung, Sections
• listings_r - Listings (inkl. inaktiver/abgelaufener/Entwürfe), Bestand, Varianten, Bilder
• transactions_r - Bestellungen (Receipts) und Kaufpositionen (Transaktionen)
• listings_w - Listings erstellen/bearbeiten/aktivieren/deaktivieren, Bestand/Preis/Bilder ändern (Stufe 2)

listings_w wird bereits beim ersten Login mitangefordert, damit nach späterem Freischalten von ETSY_WRITE_ENABLED kein erneuter Login nötig ist - Etsy erlaubt keine nachträgliche Scope-Erweiterung ohne neue Autorisierung. Der Scope allein aktiviert aber keine Schreibfunktion; das übernimmt ausschließlich ETSY_WRITE_ENABLED zusammen mit der Einzelbestätigung je Tool. Es werden keine Lösch-Scopes (listings_d) und keine Shop-/Transaktions-Schreib-Scopes (shops_w, transactions_w) angefragt.

OAuth-Anmeldung

1. In Claude das Tool etsy_auth_login aufrufen (oder direkt: npm start und in einem MCP-Client aufrufen).
2. Es öffnet sich automatisch der Browser mit der Etsy-Autorisierungsseite.
3. Bei Etsy anmelden und den Zugriff für den WandPad-Shop bestätigen.
4. Der Browser zeigt "Erfolgreich verbunden" - das Fenster kann geschlossen werden.
5. Access Token und Refresh Token werden lokal unter .secrets/etsy-tokens.json mit den Dateirechten 0600 gespeichert.

Technischer Ablauf (zur Nachvollziehbarkeit): PKCE-code_verifier/code_challenge (SHA-256, RFC 7636) werden lokal erzeugt, ein einmaliger state-Wert schützt vor CSRF, der lokale HTTPS-Server nimmt den Callback entgegen, prüft state und tauscht den Code serverseitig gegen Tokens - der code_verifier verlässt den Rechner nie unverschlüsselt sichtbar in der URL.

Start des MCP-Servers

Für den eigenständigen Start (z.B. zum Testen):

npm start

Der Server kommuniziert über stdio und ist für den Betrieb durch einen MCP-Client (Claude Desktop, Claude Code) gedacht, nicht für interaktive Terminal-Nutzung.

Verbindung zu Claude Desktop

Eintrag in ~/Library/Application Support/Claude/claude_desktop_config.json (bereits eingetragen):

{
  "mcpServers": {
    "wandpad-etsy": {
      "command": "node",
      "args": [
        "/Users/Dodo/Library/Mobile Documents/com~apple~CloudDocs/Documents/Claude Code/dist/index.js"
      ]
    }
  }
}

Danach Claude Desktop vollständig neu starten: Cmd+Q (nicht nur das Fenster schließen), dann erneut öffnen.

Verbindung prüfen: In Claude Desktop unten im Chat-Eingabefeld auf das Werkzeug-/Stecker-Symbol klicken - wandpad-etsy sollte mit einem grünen Punkt als verbunden erscheinen, mit den Tools aus der Liste unten.

Fehlerprotokolle: ~/Library/Logs/Claude/mcp*.log (bei Verbindungsproblemen dort nachsehen).

Manueller Start zur Fehlersuche:

node "/Users/Dodo/Library/Mobile Documents/com~apple~CloudDocs/Documents/Claude Code/dist/index.js"

Läuft der Server, bleibt der Prozess ohne Ausgabe auf stdout hängen (das ist korrekt - stdout ist für das MCP-Protokoll reserviert). Fehler erscheinen auf stderr im Terminal. Mit Ctrl+C beenden.

Verbindung zu Claude Code

Im Projektordner liegt bereits eine .mcp.json:

{
  "mcpServers": {
    "wandpad-etsy": {
      "command": "node",
      "args": [
        "/Users/Dodo/Library/Mobile Documents/com~apple~CloudDocs/Documents/Claude Code/dist/index.js"
      ]
    }
  }
}

Öffnest du Claude Code in diesem Ordner, wird der Server automatisch erkannt (ggf. mit Bestätigung beim ersten Start, ob dem Projekt-MCP-Server vertraut wird).

Erster Lesetest

Nach erfolgreichem Login in Claude z.B. fragen:

• "Zeig mir die Etsy-Shopdaten von WandPad." → etsy_get_shop
• "Liste meine aktiven Etsy-Listings auf." → etsy_list_listings
• "Wie ist der Bestand von Listing 4393511816?" → etsy_get_listing_inventory
• "Analysiere meinen Etsy-Shop." → etsy_analyze_shop

Shopdaten abrufen

etsy_get_shop liefert Name, Titel, Währung, Anzahl aktiver Listings, Favoriten, Bewertungsdurchschnitt, Urlaubsmodus.

Listings abrufen

etsy_list_listings (Filter: state = active/inactive/draft/expired/sold_out, limit max. 100, offset), etsy_get_listing für ein einzelnes Listing.

Bestände und Varianten abrufen

etsy_get_listing_inventory liefert Varianten (Products/Offerings), SKUs, Preise je Variante, Bestand.

Bestellungen analysieren

etsy_get_receipts (Bestellungen/"Receipts", Zeitraum max. 366 Tage, ohne Käufername/Adresse - siehe Datenschutz) und etsy_get_receipt_transactions (verkaufte Positionen je Listing/SKU).

Verfügbare Tools

Alle mit Stufe 2 markierten Tools sind nur wirksam, wenn ETSY_WRITE_ENABLED=true lokal gesetzt ist (siehe Späteren Schreibmodus aktivieren), und verlangen unabhängig davon dry_run/confirm/confirm_bulk.

Hinweis zu Etsy-Terminologie: Etsy kennt keinen separaten "Order"-Begriff - eine Bestellung heißt in der API "Receipt". etsy_get_receipts deckt deshalb sowohl "Bestellungen abrufen" als auch "Receipts abrufen" ab, statt zwei identische Tools zu duplizieren.

etsy_analyze_shop trennt strikt:

1. Fakten - unverändert von Etsy (Shop, Listings, Sections)
2. Kennzahlen - deterministisch berechnet (Preisspanne, Durchschnittspreis, Tag-Anzahl, fehlende Shop-Section, kurze Titel, wenige Tags, mögliche Titel-Duplikate, optional fehlende SKUs/niedriger Bestand)

Das Tool liefert bewusst keine fertigen Empfehlungen - Interpretation und Handlungsvorschläge (Topseller, SEO-Optimierungen etc.) soll Claude selbst auf Basis dieser Rohdaten formulieren, damit klar bleibt, was Fakt und was Einschätzung ist.

Tokens erneuern

Access Tokens laufen nach 1 Stunde ab. Der Server erneuert sie automatisch kurz vor Ablauf (über den Refresh Token, gültig 90 Tage) - dafür ist kein manuelles Eingreifen nötig. Nur wenn der Refresh Token selbst abgelaufen/ungültig ist, ist ein erneuter etsy_auth_login nötig.

Tokens zurücksetzen (Logout)

etsy_auth_logout

entfernt .secrets/etsy-tokens.json. Ein erneutes etsy_auth_login ist danach jederzeit möglich.

Fehlerbehebung

HTTP 403 "Invalid API credentials" (auch beim unauthentifizierten Ping): Keystring oder Shared Secret falsch/unvollständig kopiert, oder der API-Key-Status ist noch "Pending" statt "Active" im Etsy-Dashboard. Shared Secret im Dashboard über das Augen-Symbol vollständig aufdecken und neu kopieren.

"Zeitüberschreitung: Es wurde keine Etsy-Autorisierung innerhalb von 5 Minuten empfangen": Login-Vorgang im Browser wurde nicht abgeschlossen. etsy_auth_login erneut aufrufen.

"state-Wert stimmte nicht überein": Mögliche CSRF-Manipulation oder ein alter, bereits verbrauchter Autorisierungslink wurde erneut geöffnet. Login neu starten.

Zertifikatswarnung im Browser beim Login: Erwartet, da selbstsigniert (siehe Callback-URL). Für localhost unbedenklich bestätigen.

Claude Desktop zeigt den Server nicht als verbunden: Prüfe ~/Library/Logs/Claude/mcp*.log, stelle sicher, dass npm run build gelaufen ist (Datei dist/index.js muss existieren) und starte Claude Desktop komplett neu (Cmd+Q, nicht nur Fenster schließen).

Rate-Limit-Fehler (HTTP 429): Der Client wiederholt automatisch mit exponentiellem Backoff (bis zu 3 Versuche). Bei dauerhaften 429ern: Etsy-Rate-Limit für diese App im Dashboard prüfen.

Datenschutz

• etsy_get_receipts gibt keinen Käufernamen, keine Adresse, keine PLZ/Stadt und keine Kontaktdaten zurück - nur Status, grobes Land, Summen und Zeitstempel.
• Das Audit-Log (nur für Stufe 2 relevant) verweigert das Schreiben, sobald es Tokens, Secrets oder personenbezogene Felder (Name, Adresse, E-Mail, PLZ, Stadt) enthält - technisch erzwungen, nicht nur per Konvention.
• Es werden keine Käuferdaten in Tests, Logs oder Terminal-Ausgaben verwendet.
• Tokens, Secrets und API-Keys werden nie protokolliert (der Logger redigiert entsprechende Felder zusätzlich automatisch als zweite Sicherheitsebene).

Sicherheitsregeln

• Schreib-Tools sind nur wirksam, wenn ETSY_WRITE_ENABLED=true lokal gesetzt ist (Default: false). Jedes Schreib-Tool prüft das zusätzlich selbst zur Laufzeit (assertWriteEnabled) - ein vergessener Check in einem einzelnen Tool kann das Flag nicht umgehen.
• Jedes Schreib-Tool hat dry_run:true als Default und zeigt nur eine Vorschau, bis dry_run:false UND confirm:true explizit gesetzt sind.
• Betrifft eine Aktion mehr als ein Listing gleichzeitig, ist zusätzlich confirm_bulk:true erforderlich.
• Es gibt keine Lösch-Funktion für Listings und wird es nie geben.
• Alle echten Schreibaktionen werden im lokalen Audit-Log protokolliert; das Log verweigert technisch das Schreiben, sobald Tokens, Secrets oder personenbezogene Felder darin vorkommen.
• Bild-Uploads akzeptieren ausschließlich lokale Dateipfade, keine URLs - es wird nichts von externen Quellen heruntergeladen.
• .env, .secrets/ (Tokens, TLS-Zertifikat, Audit-Log) sind über .gitignore von Git ausgeschlossen.
• Token-Datei und Audit-Log werden mit den Dateirechten 0600 (nur Eigentümer) angelegt.
• stdout ist ausschließlich für das MCP-Protokoll reserviert - alle Log-Ausgaben (inkl. der von dotenv) gehen nach stderr, um das Protokoll nicht zu korrumpieren.
• Alle Tool-Eingaben werden mit Zod validiert: IDs müssen numerisch sein, Seitengrößen sind auf max. 100 begrenzt, Bestellzeiträume auf max. 366 Tage.

Bekannte Einschränkungen der Etsy API

• Seit 2026-02-09 verlangt Etsy für jede Anfrage das Shared Secret im x-api-key-Header (keystring:secret), nicht mehr nur den Keystring allein.

Korrektur (2026-08-06): Frühere Recherche (u.a. github.com/etsy/open-api/discussions/1386) hatte nahegelegt, dass Etsy keine Aufruf-/Besucherstatistik (views) liefert. Ein Livetest gegen die echte API zeigte, dass das Feld views tatsächlich sowohl bei etsy_get_listing als auch bei etsy_list_listings vorhanden ist und korrekte Werte liefert. etsy_analyze_shop berücksichtigt views deshalb jetzt (Durchschnitt, Listings mit unterdurchschnittlich wenigen Aufrufen).

Schreibmodus aktivieren (Stufe 2)

1. Erneut anmelden, falls der letzte Login vor der Stufe-2-Einführung war (Token muss den Scope listings_w enthalten): etsy_auth_logout gefolgt von etsy_auth_login. etsy_auth_status zeigt den aktuellen Scope.
2. In der lokalen .env setzen: ETSY_WRITE_ENABLED=true.
3. Claude Desktop neu starten (Cmd+Q, dann erneut öffnen), damit der Server die neue Umgebungsvariable liest.
4. Jedes Schreib-Tool danach zuerst ohne confirm aufrufen lassen (Default dry_run:true) - das zeigt nur die geplante Änderung. Erst nach ausdrücklicher Zustimmung im Chat mit dry_run:false und confirm:true (bei mehreren Listings zusätzlich confirm_bulk:true) erneut aufrufen.

Verfügbare Schreib-Tools: etsy_create_draft_listing (immer als Entwurf), etsy_update_listing, etsy_update_tags, etsy_update_price, etsy_update_inventory, etsy_update_variations, etsy_upload_listing_image, etsy_reorder_listing_images, etsy_activate_listing, etsy_deactivate_listing.

Design-Hinweis: Preis- und Bestandsänderungen (etsy_update_price, etsy_update_inventory) sowie Varianten-Änderungen wirken auf jeweils ein Listing pro Aufruf, da Etsys updateListingInventory-Endpunkt die komplette Varianten-Struktur eines Listings ersetzt (kein Teil-Update) und sich Varianten zwischen Listings unterscheiden. etsy_update_tags, etsy_activate_listing und etsy_deactivate_listing unterstützen dagegen mehrere Listings gleichzeitig (listing_ids), da hier dieselbe Änderung sinnvoll auf viele Listings angewendet werden kann - dafür greift die Sammelbestätigung (confirm_bulk).

Um Stufe 2 wieder zu deaktivieren: ETSY_WRITE_ENABLED=false in der .env setzen und Claude Desktop neu starten.

Gehostetes Deployment für Cowork-Agenten

Claude Desktop/Code verbindet sich lokal über stdio (ein Kindprozess pro Verbindung). Cowork-Agenten laufen dagegen nicht auf diesem Mac, sondern brauchen einen über HTTPS erreichbaren MCP-Server. Derselbe Code unterstützt deshalb zusätzlich einen HTTP-Modus (Streamable HTTP, Pfad /mcp) - welcher Modus läuft, wird automatisch anhand der Umgebungsvariable PORT entschieden (von Hosting-Plattformen wie Render automatisch gesetzt; lokal nicht vorhanden → stdio).

Deployment auf Render

1. Auf render.com einloggen (gleiches Konto wie beim WooCommerce-Connector) → New → Web Service

2. Das GitHub-Repo DodoNic/wandpad-etsy-mcp verbinden

3. Einstellungen:

   • Build Command: npm install && npm run build
   • Start Command: npm start
   • Region/Plan: frei wählbar (Free-Plan reicht zum Testen, siehe Hinweis zu persistentem Speicher unten)

4. Unter Environment folgende Variablen eintragen (gleiche Werte wie lokal in .env, außer wo anders angegeben):

   Variable	Wert
   ETSY_API_KEY	dein Keystring
   ETSY_SHARED_SECRET	dein Shared Secret
   ETSY_REDIRECT_URI	https://<dein-service-name>.onrender.com/oauth/callback (Render zeigt dir die Domain nach dem ersten Deploy)
   ETSY_SHOP_ID	wie lokal (optional)
   ETSY_SHOP_NAME	WandPad
   ETSY_WRITE_ENABLED	false zum Start - erst nach erfolgreichem Test auf true
   ETSY_MCP_AUTH_TOKEN	ein langes Zufalls-Token (z.B. mit openssl rand -hex 32 erzeugen) - schützt den öffentlichen Endpunkt

   PORT musst du nicht setzen - Render setzt das automatisch.

5. Deployen. Render zeigt danach die öffentliche URL, z.B. https://wandpad-etsy-mcp.onrender.com.

Etsy-App um die neue Callback-URL ergänzen

In deiner Etsy-App unter etsy.com/developers/your-apps die Render-Callback-URL zusätzlich zur lokalen eintragen (beide können gleichzeitig registriert sein):

https://<dein-service-name>.onrender.com/oauth/callback

Anmeldung beim gehosteten Server

Der gehostete Server hat sein eigenes, vom lokalen Login unabhängiges Token - einmalig einloggen:

1. etsy_auth_login auf dem gehosteten Server aufrufen (z.B. über den Cowork-Connector, sobald verbunden - siehe unten) - liefert sofort eine Autorisierungs-URL zurück (blockiert nicht, da der Server keinen eigenen Browser öffnen kann)
2. Die URL selbst im Browser öffnen und autorisieren
3. Mit etsy_auth_status bestätigen, dass die Anmeldung angekommen ist

Als Cowork-Connector verbinden

In den App-Einstellungen unter Connectors → Hinzufügen → Benutzerdefinierten Connector hinzufügen:

• Name: wandpad-etsy
• Remote MCP Server URL: https://<dein-service-name>.onrender.com/mcp?token=<dein ETSY_MCP_AUTH_TOKEN>

Das Token wird hier als Query-Parameter an die URL gehängt, da der Connector-Dialog nur ein URL-Feld ohne separate Header-Konfiguration bietet (die "OAuth Client ID/Secret"-Felder sind für einen vollständigen OAuth-Handshake gedacht, den dieser Server nicht implementiert). Danach kann der Connector einem oder mehreren Agenten im WandPad-Projekt zugewiesen werden, inklusive granularer Tool-Berechtigungen ("Immer erlauben" / Rückfrage / Verboten) pro Tool.

Wichtige Einschränkungen im Hosted-Modus

• Persistenter Speicher: Tokens (.secrets/etsy-tokens.json) und Audit-Log liegen auf Renders Dateisystem. Auf dem Free-Plan ist das Dateisystem flüchtig - bei jedem Neustart/Redeploy sind die Tokens weg und etsy_auth_login muss erneut ausgeführt werden. Für dauerhafte Anmeldung: Render Persistent Disk (kostenpflichtiger Plan) hinzufügen, an einen Pfad mounten (z.B. /data) und ETSY_TOKEN_PATH=/data/etsy-tokens.json sowie ETSY_AUDIT_LOG_PATH=/data/audit.log als zusätzliche Umgebungsvariablen setzen.
• Kein technischer Beweis für menschliche Bestätigung: confirm:true ist weiterhin Pflicht für echte Schreibaktionen, aber der Server kann nicht prüfen, ob wirklich ein Mensch zugestimmt hat - das hängt von der Steuerung des jeweiligen Agenten ab. Nutze die Tool-Berechtigungen im Cowork-Connector (z.B. Schreib-Tools auf "Rückfrage" statt "Immer erlauben"), um hier eine echte Bestätigungsebene zu erzwingen.
• Ein Token-Speicher pro Deployment: Der lokale Login (Claude Desktop) und der gehostete Login (Render) sind unabhängig - beide autorisieren denselben Etsy-Account, aber mit getrennten Tokens.

Vollständige Deinstallation

1. In Claude Desktop/Code den wandpad-etsy-Eintrag aus der MCP-Konfiguration entfernen (claude_desktop_config.json bzw. .mcp.json).
2. Etsy-Autorisierung bei Etsy selbst widerrufen (optional): etsy.com/your/account/privacy → "Apps mit Zugriff auf dein Konto".
3. Projektordner löschen (enthält .secrets/ mit lokalen Tokens und Zertifikat sowie .env mit den Zugangsdaten).
4. Claude Desktop komplett neu starten.