Agentic Ventures Wiki

zettle

2 Min. Lesezeit

Zettle MCP

Eigener MCP fuer Zettle by PayPal — POS mit Cloud-TSE (KassenSichV-konform fuer DE). Erster konkreter Kunde: Weingalerie Woehrle (siehe _index).

Status

configured — Skeleton + 6 Tools v0.1 fertig (2026-05-18), wartet auf ZETTLE_CLIENT_ID + ZETTLE_API_KEY aus Marvin’s Zettle-Account.

Setup

Komplette Anleitung im Repo-README: ~/source/mcps/mcp-zettle/README.md.

Kurz:

cd ~/source/mcps/mcp-zettle
uv tool install --force --editable .
cp .env.local.example .env.local
# Credentials von https://my.zettle.com/integrations eintragen
uv run python -m mcp_zettle.server
claude mcp add zettle --transport http http://127.0.0.1:8773/mcp

Auth

OAuth2-Client-Credentials mit JWT-Assertion gegen oauth.zettle.com/token:

  • ZETTLE_CLIENT_ID = UUID aus my.zettle.com/integrations
  • ZETTLE_API_KEY = Personal API Key (JWT-shaped), scoped auf READ:PRODUCT, READ:FINANCE, READ:PURCHASE

Token-Cache in ~/.local/share/mcp-zettle/token.json, automatischer Refresh wenn TTL abgelaufen.

Tools v0.1 (6)

ToolZweck
list_products(category?, name_contains?)SKU-Liste mit clientseitigem Filter
get_product(product_uuid)Details + Varianten
get_inventory_balance(product_uuid?)Lagerstand pro SKU oder global
list_sales(date_from, date_to, limit=100)Sales-Historie im Zeitraum
get_daily_summary(date)Tagesumsatz + MwSt-Splits + Durchschnittsbon
get_bestseller_last_7_days(top_n=10)Top-N-SKUs nach Umsatz

Tools v0.2 (geplant — Write)

  • create_refund(purchase_uuid, reason) — Storno mit Stripe/Zettle-Refund
  • update_inventory_balance(product_uuid, delta) — Bestand-Korrektur
  • create_product / update_product — SKU-Verwaltung von Voit aus

Trigger fuer v0.2: nach Phase-1-Notausgang-Bestaetigung von Woehrle.

Quirks (Stand 2026-05)

  • 4 verschiedene Base-URLs je Resource-Group (OAuth, Products, Inventory, Purchase) — im Code als Modul-Konstanten
  • Library-Filter ist clientseitig — Product Library API hat keine serverseitigen ?name=...-Filter
  • MwSt pro Line-Item als vatPercentage+vatAmount — get_daily_summary aggregiert ueber alle Items
  • Auth-Token-TTL meist 2h — Buffer 5 Min vor Ablauf wird refresht

Bekannte offene Punkte

  • Live-Test gegen echten Zettle-Account ausstehend — Auth-Flow + Endpoint-Pfade in v0.1 basieren auf Zettle-Doku-Recherche, nicht auf echtem Round-Trip
  • Pagination via lastPurchaseHash fuer >1000 Transaktionen noch nicht implementiert (Annahme: nicht relevant fuer Tagesabfragen)
  • Retry-Layer fuer 429/5xx in v0.2

Graphansicht

Backlinks