Skip to main content
Glama
JTL-Wawi Read-Only MCP Server

JTL-Wawi Read-Only MCP Server

by volkergrabbe

JTL-Wawi Read-Only MCP Server

Produktionsreifer, strikt lesender Model Context Protocol (MCP) Server für JTL-Wawi. Der Server läuft als isolierter Dienst in einem Proxmox-LXC und wird über LiteLLM an ein lokales LLM angebunden.

Zielgruppe: Innendienst und Kundensupport eines B2B/E-Commerce-Kunden, die revisionssichere Echtzeitauskunft zu Aufträgen, Kunden, Artikeln, Lagerbeständen und Versandstatus benötigen.


1. Sicherheitskonzept

Schutz

Umsetzung

Strikt read-only

Der HTTP-Client besitzt ausschließlich GET-Operationen. Ein interner Wächter wirft JtlReadOnlyViolation, sobald eine andere Methode versucht wird. Es existiert kein schreibendes Werkzeug.

Payload-Komprimierung

Jede API-Antwort wird auf ein flaches JSON mit max. 6–10 Feldern je Datensatz reduziert (durchgesetzt per Pydantic-Modellen, geprüft im Test test_every_output_model_stays_within_field_budget). Interne Metafelder der JTL-API gelangen nicht in den LLM-Kontext.

Authentifizierung

Der MCP-Server prüft jedes HTTP-Request gegen das statische Bearer-Token MCP_SERVER_AUTH_TOKEN (timing-sicherer Vergleich). Zusätzlich authentifiziert sich der Server gegenüber JTL-Wawi mit dem API-Key der Wawi.

Systemhärtung

systemd-Unit mit ProtectSystem=strict, NoNewPrivileges, leerer Capability-Liste, SystemCallFilter=@system-service, eigenem unprivilegiertem System-Benutzer.

Netz

Port 8080 nur im internen Netz freigeben; im LiteLLM-Gateway available_on_public_internet: false.


Related MCP server: weclapp-mcp-server

2. Architektur

LiteLLM / Client
      │  HTTP  POST /mcp  (Authorization: Bearer <MCP_SERVER_AUTH_TOKEN>)
      ▼
┌──────────────────────────────────────────────┐
│  JTL-Wawi MCP Server (FastMCP, Port 8080)    │
│  BearerAuthMiddleware → Tool → Payload-Filter│
└──────────────────────────────────────────────┘
      │  HTTP  GET  (Authorization: Bearer <base64-api-key>)
      ▼
JTL-Wawi API (JTL.Wawi.Rest.exe, Port 5883)  →  MSSQL (JTL-Wawi)

Verzeichnisstruktur

jtl-mcp-server/
├── pyproject.toml           # Abhängigkeiten, Entry-Point, pytest/ruff-Konfiguration
├── .env.example             # Vorlage für Umgebungsvariablen
├── .gitignore
├── README.md
├── src/
│   └── jtl_mcp/
│       ├── __init__.py
│       ├── __main__.py      # python -m jtl_mcp
│       ├── config.py        # Pydantic Settings (URL, API-Key, AppId, Timeouts, Auth-Token)
│       ├── jtl_client.py    # Async httpx-Client mit Retry, Timeout, Fehler-Mapping
│       ├── models.py        # Kompakte Output-Schemas (Token-optimiert)
│       └── server.py        # FastMCP, Bearer-Auth-Middleware, Tool-Definitionen
├── mock_env/
│   ├── jtl_erp_1.1.json     # Offizielle JTL-ERP-OpenAPI-Spec
│   ├── seed_openapi.py      # Erzeugt die Demo-Spec mit deutschen B2B-Beispieldaten
│   ├── jtl_erp_demo.json    # Aufbereitete Spec für Stoplight Prism
│   └── start_demo.sh        # Startet Prism + MCP-Server für die Live-Demo
├── tests/
│   ├── conftest.py          # Fixtures (Settings, respx-Router)
│   ├── mock_data.py         # Realistische JTL-Wawi-Payloads
│   ├── test_tools.py        # Unit-Tests (27 Tests)
│   └── test_e2e_prism.py    # E2E-Integrationstest gegen Prism (3 Tests)
└── deploy/
    ├── install.sh           # Installation als systemd-Dienst
    ├── uninstall.sh         # Deinstallation
    ├── jtl-mcp-server.service
    ├── healthcheck.sh       # Healthcheck für Monitoring
    ├── litellm_config.yaml.example
    └── PROXMOX_LXC.md       # Anleitung für den LXC-Betrieb

3. Voraussetzungen

  • Python 3.11+ (entwickelt und getestet mit 3.14)

  • JTL-Wawi 1.9 / 1.10 (oder neuer) inkl. laufender JTL-Wawi API (JTL.Wawi.Rest.exe, Standardport 5883)

  • Ein API-Key aus JTL-Wawi: Admin → Benutzer / Rechte → Benutzer → Key erzeugen

  • LiteLLM-Proxy als MCP-Gateway (optional, für den LLM-Anschluss)

  • Proxmox LXC (unprivileged) als Zielumgebung


4. Installation (Entwicklung)

cd jtl-mcp-server

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

cp .env.example .env
# .env bearbeiten: JTL_API_KEY, MCP_SERVER_AUTH_TOKEN, JTL_BASE_URL

.venv/bin/jtl-mcp-server          # bzw. python -m jtl_mcp

Der MCP-Endpunkt ist danach unter http://<host>:8080/mcp erreichbar.


5. Konfiguration

Alle Werte kommen aus Umgebungsvariablen bzw. der .env-Datei (Siehe .env.example).

JTL-Wawi API

Variable

Default

Bedeutung

JTL_BASE_URL

http://localhost:5883

Basis-URL des JTL-Wawi-API-Servers

JTL_API_PATH

/api/eazybusiness/v1

Pfad-Präfix; /rest/eazybusiness/v1 für den in Wawi integrierten REST-Server

JTL_API_KEY

–

Pflicht. API-Key aus JTL-Wawi

JTL_API_KEY_B64

false

true, falls der Key bereits base64-kodiert ist

JTL_APP_ID

–

Optionale App-Id (Dokumentation)

JTL_APP_VERSION

1.0.0

Version der registrierten App

JTL_TIMEOUT / JTL_CONNECT_TIMEOUT

20 / 10

Timeouts in Sekunden

JTL_MAX_RETRIES

3

Wiederholungen bei Timeout/429/5xx

JTL_BACKOFF_SECONDS

0.5

Basis-Wartezeit (exponentiell)

JTL_VERIFY_TLS

true

TLS-Prüfung (in Produktion aktiv)

JTL_PAGE_SIZE / JTL_MAX_PAGE_SIZE

50 / 200

Seitengrößen der Listenabfragen

MCP-Server

Variable

Default

Bedeutung

MCP_SERVER_AUTH_TOKEN

–

Pflicht. Statisches Bearer-Token für eingehende Requests

MCP_HOST / MCP_PORT

0.0.0.0 / 8080

Bind-Adresse und Port

MCP_PATH

/mcp

Pfad des Streamable-HTTP-Endpunkts

MCP_ALLOWED_HOSTS

–

Komma-Liste; gesetzt ⇒ Host-Origin-Protection aktiv

MCP_ALLOWED_ORIGINS

–

Komma-Liste erlaubter Origins

MCP_STATELESS_HTTP

false

Stateless-Modus (empfohlen hinter Load-Balancern)

MCP_LOG_LEVEL

INFO

Log-Level

Zum API-Key: Die JTL-Wawi erwartet ein base64-kodiertes Bearer-Token. Ist JTL_API_KEY der rohe GUID-String, kodiert der Server ihn automatisch (Default). Bereits kodierte Werte werden mit JTL_API_KEY_B64=true unverändert weitergereicht.


6. Werkzeuge (Tools)

6.1 Fachdaten (je Entität)

Tool

Parameter

Ergebnis

jtl_wawi_status

–

Erreichbarkeit, API-Version, Feature-Anzahl

jtl_list_customers

search, customer_number, customer_group_id, limit

Kundenliste (8 Felder)

jtl_get_customer

customer_id

Kundendetails inkl. Rechnungs-/Lieferanschrift (10 Felder)

jtl_list_items

search, category_id, limit

Artikel inkl. Preisen, EAN (10 Felder)

jtl_get_item

item_id

Artikeldetails inkl. EK-Preis, Gewichte (10 Felder)

jtl_list_warehouses

–

Lager inkl. Code und Typ (6 Felder)

jtl_get_item_stock

item_id

Bestand je Lager inkl. verfügbarer Menge (9 Felder)

jtl_list_sales_orders

sales_order_number, external_order_number, customer_id, created_since, created_until, is_cancelled, limit

Auftragsliste mit Status (10 Felder)

jtl_get_sales_order

sales_order_id

Auftragsdetails inkl. Anschriften (10 Felder)

jtl_list_sales_order_line_items

sales_order_id

Positionen des Auftrags (10 Felder)

jtl_list_shipments

sales_order_number, customer_id, limit

Versandstatus je Paket mit Tracking (9 Felder)

6.2 Support-Szenarien (vorkompilierte Fachfragen)

Diese Werkzeuge beantworten die typischen Support-Fragen in einem Durchgang und liefern das Ergebnis fertig aufbereitet:

Tool

Parameter

Ergebnis

get_order_status

sales_order_number

Auftragsnr., Kunde, Zahlungs-/Versandstatus, Summe, Tracking (10 Felder)

search_customer_orders

customer_number oder email, limit

Kundenstammdaten + Liste der Aufträge (6 Felder)

check_article_stock

sku

Artikel, VK netto, verfügbare Menge, Zulauf, Bestand je Lager (7 Felder)

get_shipment_tracking

sales_order_number

Lieferschein, Dienstleister, Tracking-ID, Versanddatum (8 Felder)

Zuordnung zu JTL-Wawi-Endpunkten

Tool

JTL-Wawi-Endpunkt (GET)

jtl_wawi_status

/feature

jtl_list_customers, jtl_get_customer

/customers, /customers/{id}

jtl_list_items, jtl_get_item

/items, /items/{id}

jtl_list_warehouses, jtl_get_item_stock

/warehouses, /stocks?itemId=…

jtl_list_sales_orders, jtl_get_sales_order

/salesOrders, /salesOrders/{id}

jtl_list_sales_order_line_items

/salesOrders/{id}/lineitems

jtl_list_shipments

/deliveryNotes

get_order_status

/salesOrders, /customers/{id}, /deliveryNotes

search_customer_orders

/customers, /salesOrders?customerId=…

check_article_stock

/items, /stocks?itemId=…, /warehouses

get_shipment_tracking

/deliveryNotes, /shippingMethods

Statusangaben werden als Text geliefert (LLM-freundlich): Zahlungsstatus unbezahlt / teilzahlung / bezahlt, Versandstatus nicht_versendet / versendet / versendet_ohne_lieferschein.


7. Anbindung an LiteLLM

Beispiel in deploy/litellm_config.yaml.example:

mcp_servers:
  jtl_wawi:
    url: "http://10.10.10.20:8080/mcp"
    transport: "http"
    auth_type: "bearer_token"
    auth_value: "os.environ/JTL_MCP_AUTH_TOKEN"
    available_on_public_internet: false

Der Wert von JTL_MCP_AUTH_TOKEN muss identisch mit MCP_SERVER_AUTH_TOKEN des MCP-Servers sein. Clients erreichen das Gateway danach unter http://<litellm-host>:4000/mcp (Auth über x-litellm-api-key).


8. Betrieb (Deployment)

Automatisiert (systemd)

sudo ./deploy/install.sh                 # Benutzer, venv, Unit, Dienst
sudo ./deploy/install.sh --no-start      # ohne Start
sudo ./deploy/uninstall.sh               # Dienst + Programm entfernen
sudo ./deploy/uninstall.sh --purge       # inkl. Konfiguration und Benutzer

Der Installer legt /etc/jtl-mcp-server/.env an (aus .env.example) – die Zugangsdaten sind danach einzutragen.

Betrieb im Proxmox-LXC

Detaillierte Anleitung (Container anlegen, Firewall, Netzwerk zur Wawi-API, Absicherung): deploy/PROXMOX_LXC.md.

Täglicher Betrieb

systemctl status jtl-mcp-server
journalctl -u jtl-mcp-server -f
systemctl restart jtl-mcp-server

Healthcheck

MCP_SERVER_AUTH_TOKEN=<token> ./deploy/healthcheck.sh http://127.0.0.1:8080/mcp

Prüft, dass ohne Token 401 kommt und mit Token eine MCP-initialize-Anfrage erfolgreich beantwortet wird (Exit 0 = gesund).


9. Tests und Qualität

.venv/bin/python -m pytest -q          # 38 Tests (34 Unit + 4 E2E)
.venv/bin/python -m ruff check .       # Linting

Abgedeckt sind: Payload-Filterung und Feldbudget je Datensatz, Parameter-Mapping der Listenabfragen, Status-Labels, base64-Bearer-Token an der JTL-API, Fehler-Mapping (401/404/Timeout), Retry-Verhalten bei 5xx, die Read-only-Zusage (kein Werkzeug schreibt, nur GET wird verwendet), die Bearer-Auth des MCP-Servers (401 ohne/falsches Token) sowie die Vollständigkeit der Tool-Registry. Der E2E-Test startet Prism und den FastMCP-Server als echte Prozesse, ruft die JTL-Tools über einen echten MCP-HTTP-Client auf und prüft den kompletten Roundtrip inklusive base64-Bearer-Token am Mock.


10. Lokaler Test & Live-Demo ohne JTL-Wawi (Prism Mock)

Für Vorführungen beim Arbeitgeber/Kunden und für Integrationstests ohne laufende Windows-/JTL-Installation wird die offizielle JTL-ERP-OpenAPI-Spec (1.1.json) mit Stoplight Prism als lokaler HTTP-Mock betrieben.

10.1 Einmalig vorbereiten

cd jtl-mcp-server

# Python-Umgebung (falls noch nicht vorhanden)
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

# Offizielle Spec liegt bereits unter mock_env/jtl_erp_1.1.json.
# Demo-Spec mit deutschen B2B-Beispieldaten erzeugen:
python3 mock_env/seed_openapi.py

Für den Prism-Mock wird Node.js >= 18 benötigt. Ohne Root-Rechte geht ein portables Node.js:

mkdir -p .tools && cd .tools
curl -fsSL https://nodejs.org/dist/v22.22.1/node-v22.22.1-linux-x64.tar.xz \
  | tar -xJ --strip-components=1
cd ..
export JTL_MCP_NODE_BIN="$PWD/.tools/node/bin"

start_demo.sh und der E2E-Test suchen Node.js automatisch im PATH, in JTL_MCP_NODE_BIN und in .tools/node/bin.

seed_openapi.py erzeugt mock_env/jtl_erp_demo.json und

  • setzt den Basispfad /api/eazybusiness/v1 vor alle Pfade (Prism ignoriert den servers-Block der Spec),

  • ersetzt das OAuth2-Schema der Cloud-Spec durch ein HTTP-Bearer-Schema (on-prem JTL-Wawi sendet ein base64-kodiertes Bearer-Token),

  • hinterlegt realistische Beispieldaten für Aufträge, Kunden, Artikel, Lagerbestände und Lieferscheine.

10.2 Demo starten

./mock_env/start_demo.sh

Das Skript startet Prism auf http://127.0.0.1:5883 und den MCP-Server auf http://127.0.0.1:8099/mcp, wartet auf beide Ports und gibt den fertigen curl-Testbefehl sowie einen LiteLLM-Konfigurationsblock aus. Beenden mit Ctrl+C; der EXIT-Trap räumt beide Prozesse auf.

10.3 curl-Tests

BASE64_TOKEN="$(printf '%s' '00000000-0000-0000-0000-000000000001' | base64 -w0)"

# Auftrag AU-2026-8841 direkt vom Prism-Mock
curl -sS -H "Authorization: Bearer ${BASE64_TOKEN}" \
  "http://127.0.0.1:5883/api/eazybusiness/v1/salesOrders?pageNumber=1&pageSize=50"

# Lieferschein LS-2026-9912 inkl. DHL-Tracking
curl -sS -H "Authorization: Bearer ${BASE64_TOKEN}" \
  "http://127.0.0.1:5883/api/eazybusiness/v1/deliveryNotes?salesOrderNumber=AU-2026-8841"

# MCP-Server: 401 ohne Token
curl -sS -o /dev/null -w '%{http_code}\n' -X POST \
  "http://127.0.0.1:8099/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'
# -> 401

# MCP-Server: initialize mit Token
curl -sS -X POST "http://127.0.0.1:8099/mcp" \
  -H "Authorization: Bearer demo-secret-token-123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'

10.4 Automatisierter E2E-Test

.venv/bin/python -m pytest tests/test_e2e_prism.py -q -s

Der Test startet Prism, einen Recording-Proxy und den FastMCP-Server selbst, ruft tools/list sowie die JTL-Tools über einen echten MCP-HTTP-Client auf und prüft:

  • 401 ohne bzw. mit falschem Bearer-Token am MCP-Server,

  • base64-kodiertes Bearer-Token, das der JTL-Client an Prism sendet,

  • die reduzierte deutsche Ausgabe (Auftrag, Kunde, Artikel, Bestand, Versand).

Eine Übergabe-Anweisung für externe Agenten (z. B. eine opencode-Instanz, die den Connector gebaut hat) liegt unter mock_env/OPENCODE_TESTANWEISUNG.md.

10.5 Tool-Zuordnung der Demo-Szenarien

Die vier Support-Werkzeuge sind als eigene, anwendungsfallbezogene Tools umgesetzt und rufen die JTL-API intern zusammen:

Fachaufgabe

Tool

Argumente

Ergebnis

Auftragsstatus

get_order_status

sales_order_number

Auftragsnr., Kunde, Zahlungs-/Versandstatus, Summe, Tracking (10 Felder)

Kundenorders

search_customer_orders

customer_number oder email

Kundenstammdaten + Liste der Aufträge

Artikelbestand

check_article_stock

sku

Artikel, VK netto, verfügbare Menge, Zulauf, Bestand je Lager

Sendungsverfolgung

get_shipment_tracking

sales_order_number

Lieferschein, Dienstleister, Tracking-ID, Versanddatum

Beispielaufrufe gegen die Demo-Umgebung:

# Session aufbauen (initialize)
SID=$(curl -sS -D - -o /dev/null -X POST "http://127.0.0.1:8099/mcp" \
  -H "Authorization: Bearer demo-secret-token-123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}' \
  | tr -d '\r' | awk -F': ' '/^mcp-session-id/ {print $2}')

curl -sS -X POST "http://127.0.0.1:8099/mcp" \
  -H "Authorization: Bearer demo-secret-token-123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: ${SID}" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_order_status","arguments":{"sales_order_number":"AU-2026-8841"}}}'

10.6 Hinweis zur Demo-Spec

mock_env/jtl_erp_demo.json ist eine aufbereitete Kopie der offiziellen Spec. Sie ist für den lokalen Mock gedacht und nicht für den Produktivbetrieb. Die Original-Spec bleibt unverändert unter mock_env/jtl_erp_1.1.json.


11. Troubleshooting

Symptom

Ursache / Lösung

401 von JTL-Wawi

JTL_API_KEY prüfen; JTL_API_KEY_B64 entsprechend setzen.

404 vom MCP-Endpunkt

Falscher MCP_PATH oder falsche Port-/Pfad-Kombination.

401 vom MCP-Server

MCP_SERVER_AUTH_TOKEN weicht vom Token des Clients ab.

Zeitüberschreitung

Erreichbarkeit der Wawi-API (Firewall, Port 5883) prüfen.

Leere Trefferlisten

search prüfen; JTL_API_PATH muss zur installierten Wawi-Version passen.

Es wird ein gültiges Bearer-Token benötigt

Token im Header Authorization: Bearer <token> senden.


12. Referenzen

Lizenz

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and automation tools to securely query ERPNext data through 16 read-only tools, with OAuth 2.0 or API-key authentication and usage telemetry.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only MCP tools for weclapp Cloud ERP, letting AI assistants retrieve customers, sales orders, invoices, articles, quotations, recurring invoices, and opportunities.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access Xentral ERP data — articles, customers, sales orders, invoices, and stock levels — through read-only MCP tools.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to retail ERP data through the official output WebService, letting users query products, stock and inventory, customers and suppliers, sales movement and billing, orders, salespeople, and store information with date-window and store filters.
      1
      MIT