Openxe MCP Server

OpenXE MCP Server

Verbinde dein OpenXE ERP mit jedem KI-Assistenten -- per MCP (Model Context Protocol).

69 Tools | 19 Resources | 5 Berichte | 11 Dashboard-KPIs | Verifiziert gegen OpenXE v1.12

Was ist das?

Dieser Server verbindet dein OpenXE ERP-System mit lokalen KI-Assistenten wie LM Studio, Ollama, OpenWebUI und anderen MCP-faehigen Clients. Du stellst Fragen auf Deutsch, und der Assistent liest und schreibt automatisch in deinem ERP -- alles lokal, keine Cloud noetig.

Beispiele:

• *"Zeig mir alle offenen Auftraege"*
• *"Erstelle einen neuen Kunden: Firma Muster GmbH, Musterstr. 1, 12345 Berlin"*
• *"Wie hoch ist der Umsatz diesen Monat?"*
• *"Welche Rechnungen sind ueberfaellig?"*
• *"Erstelle eine Bestellung bei Lieferant Mueller fuer 100 Schrauben"*

Voraussetzungen

• Node.js Version 20 oder neuer ()
• OpenXE mit aktiviertem API-Zugang
• Ein KI-Assistent der MCP unterstuetzt (LM Studio, OpenWebUI, Ollama, etc.)

Einrichtung

Schritt 1: API-Benutzer in OpenXE anlegen

1. Melde dich als Admin in OpenXE an
2. Gehe zu Administration > Einstellungen > Benutzer
3. Erstelle einen neuen Benutzer (oder verwende einen bestehenden)
4. Setze unter API > REST-API ein Passwort
5. Merke dir Benutzername und Passwort

Schritt 2: MCP-Server in deinem KI-Assistenten einrichten

Der Server wird automatisch heruntergeladen und gestartet -- du musst nichts installieren. Du brauchst nur drei Angaben:

LM Studio

Ab Version 0.3+. Oeffne Settings > MCP und fuege folgendes ein:

Minimale Konfiguration (LAN-Betrieb, schneller Einstieg):

{
  "openxe": {
    "command": "npx",
    "args": ["-y", "github:Avatarsia/openxe-mcp-server"],
    "env": {
      "OPENXE_URL": "http://192.168.0.100",
      "OPENXE_USERNAME": "api-user",
      "OPENXE_PASSWORD": "mein-passwort",
      "OPENXE_ALLOW_HTTP": "1"
    }
  }
}

Vollstaendige Konfiguration (mit allen Optionen):

{
  "openxe": {
    "command": "npx",
    "args": ["-y", "github:Avatarsia/openxe-mcp-server"],
    "env": {
      "OPENXE_URL": "http://192.168.0.100",
      "OPENXE_USERNAME": "api-user",
      "OPENXE_PASSWORD": "mein-passwort",
      "OPENXE_ALLOW_HTTP": "1",
      "OPENXE_MODE": "router",
      "OPENXE_TIMEOUT": "30000",
      "OPENXE_AUDIT_LOG": "1"
    }
  }
}

Was bedeuten die einzelnen Einstellungen?

Tipp fuer lokale Modelle: Verwende den router-Modus (Standard). Er reduziert den Token-Verbrauch von ~10.000 auf ~1.500 Tokens fuer die Tool-Definitionen -- das laesst mehr Platz fuer deine eigentliche Frage und die Antwort.

Alternative: Lokaler Build mit .env-Datei

Wenn du das Repo selbst geklont und lokal gebaut hast (npm install && npm run build), kannst du die Credentials in einer .env-Datei im Projektverzeichnis pflegen, statt sie inline in der MCP-Client-Konfiguration zu hinterlegen. Der Eintrag sieht dann so aus:

{
  "openxe": {
    "command": "node",
    "args": [
      "/openxe-mcp-server/dist/index.js"
    ],
    "cwd": "/openxe-mcp-server"
  }
}

Wichtig:

• Kein env-Block in der MCP-Client-Konfiguration — sonst ueberschreiben die inline-Werte die Eintraege aus der .env.
• cwd zwingend setzen, und zwar auf das Projektverzeichnis (openxe-mcp-server). dotenv laedt die .env aus dem aktuellen Arbeitsverzeichnis des Prozesses, nicht aus dem Verzeichnis, in dem index.js liegt. Ohne cwd startet der MCP-Client den Node-Prozess aus seinem eigenen Installationsordner, und die .env wird nicht gefunden.
• Kein npx, sondern node — npx -y github:... wuerde jedes Mal das GitHub-Package in einen Cache-Ordner ziehen und deinen lokalen Build ignorieren.
• Nach Code-Aenderungen npm run build nicht vergessen — gestartet wird dist/index.js, nicht die TypeScript-Quellen.

OpenWebUI + Ollama

Ab OpenWebUI 0.6+. Unter Admin > Tools > MCP Servers eintragen:

• Command: npx
• Args: -y github:Avatarsia/openxe-mcp-server
• Umgebungsvariablen: OPENXE_URL, OPENXE_USERNAME, OPENXE_PASSWORD

Andere MCP-Clients

Jeder Client mit stdio-Transport funktioniert:

OPENXE_URL=http://dein-openxe-server \
OPENXE_USERNAME=dein-api-user \
OPENXE_PASSWORD=dein-api-passwort \
npx -y github:Avatarsia/openxe-mcp-server

Schritt 3: Testen

Starte deinen KI-Assistenten und frage: *"Zeig mir alle Artikel"*. Wenn Daten kommen, funktioniert alles.

Funktionen

Was kann der Server?

Smart Filters

Alle Listen-Abfragen unterstuetzen clientseitige Filter:

• where: {plz: {startsWith: "2"}}, {gesamtsumme: {gt: 100}}, {land: {equals: "DE"}}, {"positionen.nummer": {containsAny: ["ART-001", "ART-002"]}}
• where-Operatoren (neu): in (Feld matcht einen Wert aus Liste), containsAny (Array-Feld enthaelt mindestens einen Wert), containsAll (Array-Feld enthaelt alle Werte). Alle drei vergleichen case-insensitive.
• Dot-Notation: Feldnamen wie positionen.nummer iterieren ueber verschachtelte Array-Felder eines Belegs. Eine einzelne Bedingung matcht "mindestens ein Element". Mehrere Bedingungen mit gleichem Array-Prefix (z.B. positionen.nummer + positionen.menge) werden automatisch elementweise gepaart — der Beleg matcht nur, wenn dasselbe Array-Element alle Bedingungen erfuellt.
• sort/limit: Ergebnisse sortieren und begrenzen
• zeitraum: dieser-monat, letzter-monat, letzte-30-tage, Q1-2026, 2025
• status_preset — entity-spezifisch, unbekannte/nicht unterstützte Werte werden vom Handler als Fehler abgewiesen:

- list-quotes: offen | angenommen | abgelehnt - list-orders: offen | entwurf - list-invoices: offen | unbezahlt | bezahlt | ueberfaellig | entwurf | mahnkandidaten - list-delivery-notes, list-credit-memos: wird nicht unterstützt - list-purchase-orders: offen | freigegeben | bestellt | angemahnt | empfangen | aktiv - Für business-query-Presets (offene-rechnungen, nicht-versendet, ueberfaellige-rechnungen, ueberfaellige-lieferungen usw.) das separate Tool openxe-business-query bzw. die action business-query nutzen.

• aggregate: count, sum_feld, avg_feld, groupBy_feld
• format: table, csv, ids, csv-positions (bei Belegen: eine CSV-Zeile pro Belegposition statt pro Beleg, mit Beleg-Header-Feldern als Prefix und Positions-Feldern dahinter; bei Filter auf positionen.* werden nur die passenden Positionen exportiert).

Beispiel (router-Modus): Rechnungen finden, die Artikel ART-001 oder ART-002 enthalten, und nur die passenden Positionen als CSV exportieren:

{
  "action": "list-invoices",
  "params": {
    "zeitraum": "2025",
    "where": {
      "positionen.nummer": {"containsAny": ["ART-001", "ART-002"]}
    },
    "format": "csv-positions"
  }
}

Im full-Modus wird derselbe Aufruf direkt als Tool openxe-list-invoices mit dem inneren params-Objekt als Argumenten verwendet.

Berichte

Konfiguration

Pflicht-Variablen

Optionale Variablen

Sicherheits-Variablen (nur fuer Netzwerk-Betrieb mit --http)

Haeufige Probleme

Der KI-Assistent findet keine Daten

• Pruefe ob die OpenXE-URL erreichbar ist: curl http://dein-openxe-server/api/index.php
• Pruefe ob Benutzername und Passwort stimmen
• Pruefe ob die Umgebungsvariablen korrekt gesetzt sind

Authentifizierung schlaegt fehl

• OpenXE nutzt HTTP Digest Auth -- der Benutzer braucht ein Passwort unter API > REST-API
• Sonderzeichen im Passwort koennen Probleme mit Umgebungsvariablen verursachen

Timeout bei grossen Abfragen

• Erhoehe OPENXE_TIMEOUT (z.B. auf 60000 fuer 60 Sekunden)
• Verwende spezifischere Abfragen statt *"zeig mir alles"*

Leere Ergebnisse bei Bestellungen

• Bestellungen (Einkauf) sind nicht ueber die REST v1 API verfuegbar -- der MCP-Server nutzt automatisch die Legacy API als Fallback
• Wenn trotzdem leer: pruefe ob Bestellungen in OpenXE existieren

Sicherheit

Lokaler Betrieb (Standard)

Im Normalfall laeuft der Server als Subprocess deines KI-Assistenten (stdio-Transport). Dabei werden keine Netzwerkports geoeffnet -- die Kommunikation laeuft ueber Pipes. Fuer den Betrieb im lokalen Netzwerk sind keine zusaetzlichen Einstellungen noetig.

Read-Only Modus

Wenn du nur Daten lesen moechtest (kein Erstellen/Bearbeiten/Loeschen):

OPENXE_MODE=readonly

Netzwerk-Betrieb (--http)

Nur wenn du den Server als eigenstaendigen Netzwerkdienst betreiben willst:

MCP_AUTH_TOKEN=dein-token npx -y github:Avatarsia/openxe-mcp-server -- --http

• Bindet standardmaessig nur auf 127.0.0.1 (nicht von aussen erreichbar)
• Mit MCP_HTTP_HOST=0.0.0.0 von aussen erreichbar -- nur hinter einem Reverse-Proxy mit HTTPS verwenden!

Tool Annotations

Alle Tools tragen MCP-Annotations (readOnlyHint, destructiveHint, idempotentHint). Dein KI-Client kann damit automatisch vor kritischen Aktionen warnen.

Fuer Entwickler

Konfiguration via .env-Datei

Der Server unterstuetzt eine .env-Datei im Projektverzeichnis. Kopiere .env.example und passe die Werte an:

cp .env.example .env

Die .env-Datei wird nicht nach Git committed (steht in .gitignore). Umgebungsvariablen die direkt gesetzt werden (z.B. ueber die MCP-Client-Konfiguration) haben Vorrang vor .env.

Projektstruktur

src/
  index.ts          # MCP-Server Einstiegspunkt (laedt dotenv)
  config.ts         # Umgebungsvariablen (Zod-validiert)
  client/           # HTTP Digest Auth Client fuer OpenXE
  tools/            # Tool Handler (Schreiben via Legacy API)
    report-tools.ts # 5 Berichts-Tools
    procurement-tools.ts # Beschaffung (Bestellungen)
    document-tools.ts    # Belege CRUD + Konvertierung
    address-tools.ts     # Adressen mit Feld-Normalisierung
    ...
  resources/        # Resource Handler (Lesen via REST v1)
  schemas/          # Zod-Schemas fuer Eingabe-Validierung
  utils/            # Smart Filters, Pagination, Aggregation
tests/              # 369 Unit-Tests (Vitest)
docs/
  api-reference/    # Verifizierte OpenXE API-Dokumentation
  llm/              # LLM-optimierte Kurzreferenz

Lokal entwickeln

git clone https://github.com/Avatarsia/openxe-mcp-server.git
cd openxe-mcp-server
npm install
cp .env.example .env     # Dann Werte anpassen
npm run build
npm test
npm start

Der Server laedt automatisch eine .env-Datei aus dem Projektverzeichnis (via dotenv). Alternativ koennen die Variablen weiterhin direkt als Umgebungsvariablen oder ueber die MCP-Client-Konfiguration gesetzt werden — .env hat die niedrigste Prioritaet.

API-Dokumentation

Verifizierte Dokumentation im Verzeichnis docs/api-reference/:

• AUTH.md -- HTTP Digest Authentifizierung, 96 Permissions
• LEGACY-API.md -- 120+ Legacy API Endpoints (Schreiben)
• REST-V1-STAMMDATEN.md -- Artikel, Adressen, Kategorien, etc.
• REST-V1-BELEGE.md -- Auftraege, Rechnungen, Lieferscheine, etc.
• REST-V1-SONSTIGE.md -- Abos, CRM, Tracking, Dateien, etc.
• SPEZIAL-APIS.md -- Shop-Import, OpenTRANS, Mobile API

Bekannte Einschraenkungen

Lizenz

MIT -- siehe LICENSE.