JTL-Wawi Read-Only MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
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 |
Authentifizierung | Der MCP-Server prüft jedes HTTP-Request gegen das statische Bearer-Token |
Systemhärtung | systemd-Unit mit |
Netz | Port 8080 nur im internen Netz freigeben; im LiteLLM-Gateway |
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-Betrieb3. 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 erzeugenLiteLLM-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_mcpDer 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 |
|
| Basis-URL des JTL-Wawi-API-Servers |
|
| Pfad-Präfix; |
| – | Pflicht. API-Key aus JTL-Wawi |
|
|
|
| – | Optionale App-Id (Dokumentation) |
|
| Version der registrierten App |
|
| Timeouts in Sekunden |
|
| Wiederholungen bei Timeout/429/5xx |
|
| Basis-Wartezeit (exponentiell) |
|
| TLS-Prüfung (in Produktion aktiv) |
|
| Seitengrößen der Listenabfragen |
MCP-Server
Variable | Default | Bedeutung |
| – | Pflicht. Statisches Bearer-Token für eingehende Requests |
|
| Bind-Adresse und Port |
|
| Pfad des Streamable-HTTP-Endpunkts |
| – | Komma-Liste; gesetzt ⇒ Host-Origin-Protection aktiv |
| – | Komma-Liste erlaubter Origins |
|
| Stateless-Modus (empfohlen hinter Load-Balancern) |
|
| Log-Level |
Zum API-Key: Die JTL-Wawi erwartet ein base64-kodiertes Bearer-Token. Ist
JTL_API_KEYder rohe GUID-String, kodiert der Server ihn automatisch (Default). Bereits kodierte Werte werden mitJTL_API_KEY_B64=trueunverändert weitergereicht.
6. Werkzeuge (Tools)
6.1 Fachdaten (je Entität)
Tool | Parameter | Ergebnis |
| – | Erreichbarkeit, API-Version, Feature-Anzahl |
|
| Kundenliste (8 Felder) |
|
| Kundendetails inkl. Rechnungs-/Lieferanschrift (10 Felder) |
|
| Artikel inkl. Preisen, EAN (10 Felder) |
|
| Artikeldetails inkl. EK-Preis, Gewichte (10 Felder) |
| – | Lager inkl. Code und Typ (6 Felder) |
|
| Bestand je Lager inkl. verfügbarer Menge (9 Felder) |
|
| Auftragsliste mit Status (10 Felder) |
|
| Auftragsdetails inkl. Anschriften (10 Felder) |
|
| Positionen des Auftrags (10 Felder) |
|
| 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 |
|
| Auftragsnr., Kunde, Zahlungs-/Versandstatus, Summe, Tracking (10 Felder) |
|
| Kundenstammdaten + Liste der Aufträge (6 Felder) |
|
| Artikel, VK netto, verfügbare Menge, Zulauf, Bestand je Lager (7 Felder) |
|
| Lieferschein, Dienstleister, Tracking-ID, Versanddatum (8 Felder) |
Zuordnung zu JTL-Wawi-Endpunkten
Tool | JTL-Wawi-Endpunkt (GET) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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: falseDer 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 BenutzerDer 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-serverHealthcheck
MCP_SERVER_AUTH_TOKEN=<token> ./deploy/healthcheck.sh http://127.0.0.1:8080/mcpPrü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 . # LintingAbgedeckt 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.pyFü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/v1vor alle Pfade (Prism ignoriert denservers-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.shDas 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 -sDer 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:
401ohne 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 |
|
| Auftragsnr., Kunde, Zahlungs-/Versandstatus, Summe, Tracking (10 Felder) |
Kundenorders |
|
| Kundenstammdaten + Liste der Aufträge |
Artikelbestand |
|
| Artikel, VK netto, verfügbare Menge, Zulauf, Bestand je Lager |
Sendungsverfolgung |
|
| 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 |
|
|
| Falscher |
|
|
| Erreichbarkeit der Wawi-API (Firewall, Port 5883) prüfen. |
Leere Trefferlisten |
|
| Token im Header |
12. Referenzen
JTL-Wawi REST-API (OpenAPI-Spec v1.1): https://developer.jtl-software.com/openapi/erp/1.1.json
JTL-Wawi Entwicklerdokumentation: https://developer.jtl-software.com/products/erpapi/openapi/
JTL-Wawi API – Instanz einrichten (JTL-Guide): https://guide.jtl-software.com/jtl-wawi/jtl-wawi-api/instanz-der-jtl-wawi-api-mit-automatischem-start-einrichten/
FastMCP – HTTP Deployment: https://gofastmcp.com/docs/deployment/http
LiteLLM – MCP Configuration Reference: https://docs.litellm.ai/docs/mcp_config_reference
Lizenz
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only access to your VortexIQ store data: audits, KPIs, alerts, Brand DNA, reports, Ask VIQ.
Read-only TVCMall customer queries: products, orders, tracking, shipping, points and balance.
Read orders, shipments, products and stock; set order status, notes and stock quantity in Apilo.
Read FinerWorks orders, inventory, catalog, prices and shipping quotes; never submits an order.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceProvides 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
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to access Xentral ERP data — articles, customers, sales orders, invoices, and stock levels — through read-only MCP tools.AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT